GFM Tables in Technical Blogs: Syntax, Alignment, and Compatibility

When a pipe character breaks your table

You are documenting a command-line tool. One flag accepts a file glob such as `src/**/*.ts`; another accepts a regular expression that includes a literal pipe, such as `error|warn`. You place both values in a GFM table row, publish the post, and discover that the renderer has split the cell into extra columns. The header no longer matches the data, and readers see a malformed grid instead of a comparison.

GitHub Flavored Markdown (GFM) tables are a convenient way to embed structured data directly in a markdown file, but they are not immune to syntax collisions. This post explains how GFM tables work, where alignment is actually honored, and how to verify that your target platform renders the table before your readers do.

GFM table syntax and alignment

A GFM table requires three parts: a header row of pipe-separated titles, a separator row with at least three hyphens per column, and one or more data rows. A colon inside the separator requests alignment: `:---` for left, `---:` for right, and `:---:` for center.

| Flag | Default | Meaning |
|:-----|:-------:|--------:|
| `--verbose` | `false` | Enable debug output |
| `--pattern` | `error|warn` | Match severity levels |

GitHub renders the alignment request, but many other markdown parsers ignore the colon and render all columns with default alignment. Treat alignment as a visual hint for GitHub readers, not a structural guarantee.

Worked example: comparing configuration formats

Suppose you need to show how two configuration files define the same timeout setting.

| Format | File | Timeout key | Unit |
|:---|:---|:---|---:|
| YAML | `config.yaml` | `request_timeout` | seconds |
| TOML | `config.toml` | `request_timeout` | seconds |

The right-aligned unit column makes numeric values easier to scan on GitHub. On a CommonMark-only renderer, the same source may appear as plain text with visible pipes rather than a grid.

Verify before you publish

Run the markdown through your target pipeline and inspect the output.

1. Open the file in a GFM-compatible viewer, such as GitHub.com or a local previewer configured for `markdown_github`.
2. Confirm the header row appears as a table and that the column count matches the separator row.
3. Run a CommonMark-only processor to observe the fallback behavior:

pandoc -f commonmark -t plain yourfile.md

Where to run: your local terminal. Permissions: read access to `yourfile.md`; no elevated privileges required. Expected check: if the processor lacks GFM table support, the pipes appear as literal text rather than a structured grid. Risk: pandoc built without the `pipe_tables` extension will not recognize GFM tables even when the source is valid GFM.

Limitations

• A literal pipe character inside a cell creates extra columns unless your renderer supports escaping. Rephrase the content or avoid pipes in table text.
• Not all static site generators enable GFM extensions. A table that looks correct on GitHub may break in your build output.
• Tables interrupt reading flow. Use them for side-by-side data, not for narrative lists.

Actionable closing

1. Identify data that benefits from side-by-side comparison.
2. Write the header, then a separator line with at least three hyphens per column.
3. Add data rows with the same number of pipe delimiters.
4. Preview in a GFM-compatible viewer and in a CommonMark-only processor.
5. If the CommonMark output shows literal pipes, decide whether your audience uses GFM; otherwise fall back to a definition list or plain text.

GFM tables reduce the need for external assets, but only when your renderer supports them. Test on the actual publishing platform before you commit.