Guides for Markdown Editor and Reader
How to make tables in Markdown
Tables are not part of the original Markdown or of CommonMark. They come from GitHub Flavored Markdown (GFM), and because GitHub popularized them, almost every modern Markdown editor and site generator supports the same pipe syntax.
This guide covers the basic structure, column alignment, escaping and formatting inside cells, and the limits you will run into sooner or later.
The basic structure
A Markdown table has three parts: a header row, a delimiter row and any number of body rows. Pipes (|) separate the cells. The delimiter row consists of hyphens, one group per column, and tells the renderer that the lines above and below form a table.
| Fruit | Price | In stock |
| ------ | ----: | :------: |
| Apple | 1.20 | yes |
| Pear | 0.90 | no |
| Banana | 0.35 | yes |The rules that matter
The shortest valid form works, but it is harder to read:
Name | Role
--- | ---
Ada | Admin
Linus | Editor- The header row is required. GFM has no tables without a header.
- The delimiter row must have exactly as many cells as the header row, otherwise the block is not recognized as a table.
- Each delimiter cell needs at least one hyphen. Three is the common convention and is understood everywhere.
- Body rows with fewer cells are filled with empty cells; extra cells are ignored.
- Leading and trailing pipes are optional, but they make the source easier to read. For a single-column table, keep them.
- The columns do not have to line up in the source. Spaces around cell content are trimmed.
- The table ends at the first blank line or at the start of another block such as a heading or a list. Leave a blank line before the table as well.
Aligning columns
Colons in the delimiter row set the alignment of a whole column, header included. Right alignment is useful for numbers, so the decimal places line up.
| Delimiter cell | Alignment |
|---|---|
| --- | | Default (usually left) |
| :--- | | Left |
| :---: | | Center |
| ---: | | Right |
Formatting inside cells
Cells may contain inline Markdown (see the Markdown cheat sheet): bold, italic, code, links, images and strikethrough. Block elements are not possible: no lists, no headings, no code blocks and no paragraphs inside a cell.
| Command | Description |
| ------------ | -------------------------- |
| `git status` | Shows **changed** files |
| `git log` | See the [docs](https://git-scm.com/docs) |Escaping the pipe character
A pipe inside a cell would start a new column. Write \| instead. In GFM this also applies inside code spans within a table: `a \| b` is displayed as a | b in code formatting.
| Operator | Meaning |
| -------- | --------- |
| `a \| b` | a or b |
| \|x\| | absolute value |What Markdown tables can't do
The pipe syntax is deliberately simple. If you need any of the following, you have to fall back to an HTML table, and only where your renderer allows HTML:
- Merged cells (no colspan or rowspan)
- Multiple paragraphs or lists within a cell
- Captions
- Fixed column widths
- Tables without a header row
Line breaks in cells
A cell must fit on one line of source. Many renderers, including GitHub, accept the HTML tag <br> inside a cell to force a line break. Whether that works elsewhere depends on whether the renderer lets HTML through.
Turning a spreadsheet into a Markdown table
If you copy cells from Excel, Numbers or Google Sheets and paste them into a text editor, you usually get the values separated by tabs, not a Markdown table. Replace the tabs with pipes, add a delimiter row with one --- per column below the first line, and the result is a valid table. For large tables, a converter tool or a script saves time; check the output once, because merged cells and line breaks in the spreadsheet have no Markdown equivalent.
Writing tables on iPhone and iPad
Typing pipes and hyphens on a phone keyboard is fiddly. In Markdown Editor, the formatting bar above the keyboard inserts a table with one tap, and the preview shows it formatted as a real table; on iPad you see the source and the live preview side by side, so a missing pipe stands out immediately. Your documents stay plain .md files in the Files app. With Markdown Editor Pro you can export them as formatted PDF or HTML. More tips for the touch keyboard: writing Markdown on iPhone and iPad.
Frequently asked questions
How do I align a column in a Markdown table?
Put colons in the delimiter row: :--- for left, :---: for center and ---: for right. The alignment applies to the whole column.
Can I make a Markdown table without a header row?
No. GFM requires a header row and the delimiter row below it. A common workaround is a header row with empty cells, but many renderers still draw it as an empty line.
Can I merge cells in a Markdown table?
No. Markdown tables have no colspan or rowspan. If you need merged cells, use an HTML table in a renderer that allows HTML.
How do I put a | inside a table cell?
Escape it with a backslash: \|. In GitHub Flavored Markdown this also works inside code spans within the table.
How do I add a line break inside a table cell?
Each row must stay on one line of source. Where HTML is allowed, as on GitHub, write <br> at the point where the line should break.
Do Markdown tables work everywhere?
Not everywhere. Tables come from GitHub Flavored Markdown, so they work on GitHub and in most modern editors and site generators, but not in renderers that support only strict CommonMark or the original Markdown.