GFM Table Cheatsheet: Copyable Syntax and Rendered Output

TL;DR — GFM table cheatsheet

• A table is a header row, a separator row (---, at least three hyphens per column), and data rows, all split by pipes |. A blank line is required before and after the table.
• Alignment is set by colons in the separator row: :--- left, :---: center, ---: right.
• A literal pipe inside a cell is \| (backslash escape); | (HTML entity) is the fallback when a renderer mishandles the backslash form.
• A visible line break inside a cell is a raw <br> tag. It works on GitHub and GitLab; Obsidian, Notion, and others vary by edit mode or import path.
• Cell merging, multiple paragraphs, code blocks, and other block elements are not possible in GFM tables. Use an HTML <table> when you need them.
• Don't want to type pipes by hand? Paste CSV into CSV to Markdown and get a GFM-compatible table instantly.

This is a quick-reference card for people who already know roughly how to write a Markdown table. If you want to learn how to build one from scratch, start with Tables in Markdown: Syntax, Alignment & Copy-Paste Examples.

What GFM tables can and cannot do

When you need block elements or merged cells, write an HTML <table> directly in your Markdown (see "What Markdown tables can't do" below).

Basic structure — the minimal pair

A GFM table has three parts: a header row, a separator row, and data rows. The separator needs at least three hyphens per column; leading and trailing pipes are optional.

Syntax:

| Name | Role |
| --- | --- |
| Mika | admin |
| Noah | viewer |

Rendered:

The smallest possible table (one header row + one data row):

| key | value |
| --- | --- |
| name | FormatArc |

Alignment syntax cheatsheet

The position of the colons in the separator row sets column alignment.

Syntax:

| Product | Qty | Price |
| :--- | :---: | ---: |
| Apples | 3 | 1.20 |
| Oranges | 10 | 0.80 |

Rendered:

Right-aligning numeric columns keeps digits lined up and easier to scan.

Inline formatting inside cells

Cells accept inline elements. Code blocks, lists, and multiple paragraphs are not allowed.

Images work in cells, but they make the table tall and hard to read, so small icons are the practical limit.

Escaping pipes and special characters

A literal | inside a cell collides with the column separator and breaks the table. Two safe ways to write one:

Syntax:

| Command | Meaning |
| --- | --- |
| cmd1 \| cmd2 | backslash escape |
| cmd1 | cmd2 | HTML entity |

Rendered:

To show a literal backslash, write \\; for a non-breaking space, use  . If you build tables from CSV or HTML, pipe escaping is handled for you by CSV to Markdown and HTML to Markdown, so you don't have to think about it.

Line breaks inside cells, by platform

The Markdown table spec does not support raw newlines inside a cell. For a visible break, write a raw <br> tag — but support varies.

If a table needs reliable line breaks in many columns, don't force it into a GFM table — use an HTML <table> or split the columns.

Why tables break — a checklist

When a table renders wrong, check these from the top:

• Is there a blank line before and after the table? — A table jammed against the previous line may not be recognized (especially on GitHub)
• Is there a header row? — GFM requires one. If you don't want visible headers, you still need an empty header row plus the separator
• Does the separator row have at least three hyphens per column? — -- won't render as a table in some renderers
• Do the header, separator, and data rows have the same number of columns (pipes)? — Short data rows are padded with empty cells; long ones have the extra cells dropped
• Is there an unescaped | inside a cell? — If so, change it to \| or |
• Is a row indented (four or more leading spaces)? — It can be mistaken for a code block
• Is there a block element (code block, list) inside a cell? — Not allowed in GFM tables

Generate tables from CSV / HTML / JSON

Hand-writing a five-row table is fine. Past 20 rows, or with many columns, pipe alignment and escaping become error-prone. Depending on your source format, a FormatArc tool turns it into a GFM-compatible table in one step.

• From CSV / a spreadsheet / Excel: paste into CSV to Markdown and run. For a walkthrough, see How to Convert CSV to a Markdown Table; for README use, see Adding a Table to a GitHub README.
• From existing HTML (a web page table, a Notion export, a CMS dump): paste the HTML into HTML to Markdown and <table> elements become pipe tables. See the HTML to Markdown guide.
• From JSON (an API response or logs): route it through CSV. Build a CSV where each object's keys are the column names and the values are the row cells, then feed it to CSV to Markdown. See the "Building a table from JSON data" section in Adding a Table to a GitHub README.
• To paste the resulting Markdown table into a CMS that doesn't support Markdown, or into an HTML email, convert it with Markdown to HTML. See the Markdown to HTML guide.

Everything runs in your browser, so internal data and customer lists are never sent to a server. No sign-up, no upload.

What Markdown tables can't do — when to switch to HTML

GFM tables can't express the following. Switch to a raw HTML <table> inside your Markdown instead:

• Merged cells across rows or columns (rowspan / colspan)
• Bulleted lists, multiple paragraphs, or code blocks inside a cell
• Fixed column widths in pixels or percentages
• A heading or another table nested inside a table

Note that GitHub and similar platforms restrict in-table HTML for security: <br> passes through, but inline styles like <span style="..."> are ignored, so you cannot change colors or font sizes that way.

CommonMark and tables

Plain CommonMark does not define table syntax. Pipe tables are a GFM extension, defined in the Tables (extension) section of the GitHub Flavored Markdown spec. A renderer that implements strict CommonMark with no extensions will show | col | as plain text, not a table. The fastest way to tell whether your tool is GFM-compatible is to write one simple table and see if it renders.

Frequently asked questions

What is the smallest Markdown table?

Three lines: one header row, one separator row, one data row. Write | key | value |, then | --- | --- | below it, then | name | FormatArc |. The separator row needs at least three hyphens per column.

Should I use \| or |?

Use the backslash escape \| first. It's documented by GitHub and works in most GFM renderers. Fall back to | only when a renderer mishandles \| or when copy-pasting between editors breaks it.

Can I change text color or font size inside a cell?

Not with GFM tables alone. GitHub and similar platforms ignore inline styles like <span style="..."> inside tables, so color and size changes don't apply. If you must style cells, pull the table out and use HTML, or rethink the layout.

Is there a guideline for column widths?

Markdown has no column-width syntax; renderers size columns to fit the content. As a practical rule, if a README or doc is read on both desktop and mobile, keep tables to five or six columns. Beyond that, GitHub adds horizontal scrolling and the table gets hard to read.

Can I merge cells (rowspan / colspan)?

Not in GFM tables. For merged cells, write an HTML <table> directly in your Markdown — but check the rendered output first, since GitHub and others restrict some HTML attributes.

My table shows up as | col | instead of rendering. Why?

The usual causes: no blank line before or after the table, fewer than three hyphens in the separator row, no header row, mismatched column counts, or a renderer that doesn't support the GFM table extension (strict CommonMark). Work through the "Why tables break" checklist above from the top.

Related articles

• Tables in Markdown: Syntax, Alignment & Copy-Paste Examples — a step-by-step tutorial for building a table from scratch
• How to Convert CSV to a Markdown Table — one-step conversion from Excel or spreadsheet data
• Adding a Table to a GitHub README — generate README tables from CSV / JSON
• Markdown to HTML conversion guide — paste your table into a CMS that doesn't support Markdown
• HTML to Markdown guide — extract tables from web pages or Notion exports