How do you make a table in markdown?

Write the header row with pipes between columns, add a separator row of dashes underneath, then add one line per body row. Leave a blank line above the table so it renders.

How do I align columns in a markdown table?

Add colons to the separator row: :--- aligns left, :---: centers and ---: aligns right. Right alignment suits numbers.

How do I put a pipe character inside a markdown table cell?

Escape it with a backslash, written as \|. An unescaped pipe is read as a column boundary and shifts the cells.

Can a markdown table have merged cells or multiple lines in a cell?

Not in plain markdown. Each row is a single line, and merged cells, lists and multi-paragraph cells are not supported. Some renderers accept an inline br tag for a line break, but it varies.

Why is my markdown table not rendering?

The usual causes are a missing separator row, no blank line above the table, or different column counts between rows. Fix those first, then check for unescaped pipes.

Are markdown tables part of standard markdown?

Tables come from the GitHub Flavored Markdown extension rather than the original markdown. Most modern editors and converters support them, but a minimal renderer may not.

Markdown Tables Explained: Syntax, Alignment and Examples

Quick answer

A markdown table uses pipes (|) between columns and a row of dashes under the header: | Name | Role |, then | --- | --- |, then your rows. Add colons to the dashes to align columns.

A markdown table is built from pipes and dashes: a header row, a separator row, then body rows. Tables are an extension from GitHub Flavored Markdown rather than part of the original markdown, but most modern editors and exporters support them. This guide covers the syntax, alignment, what you can put in a cell, how to fix a table that will not render, and when to use something else.

The basic table

| Name | Role   |
| ---- | ------ |
| Ada  | Writer |
| Sam  | Editor |

There are three parts. The first line is the header row. The second line is the separator row, made of at least three dashes per column (some renderers accept fewer, but three is safe). Every line after that is a body row. The pipes do not have to line up, because the renderer ignores the extra spaces, but aligning them makes the source much easier to read and edit.

The outer pipes at the start and end of each line are optional in most renderers, though including them avoids surprises:

Name | Role
--- | ---
Ada | Writer

Column alignment

Colons in the separator row control alignment. A colon on the left aligns left, on both sides centers, and on the right aligns right.

| Item      | Qty | Price |
| :-------- | :-: | ----: |
| Notebook  |  2  |  4.50 |
| Pen       | 10  |  1.25 |

Right alignment is the right choice for numbers, because digits then line up by place value. Text columns are normally left aligned, which is also the default when you use plain dashes. Some very basic renderers ignore alignment entirely, so do not make the meaning of a table depend on it.

Formatting inside cells

Cells can contain inline formatting: bold, italic, inline code, strikethrough and links.

| Action | Shortcut | Notes |
| --- | --- | --- |
| **Bold** | `Cmd+B` | Wraps the selection |
| *Link* | `Cmd+K` | See [the cheat sheet](/blog/markdown-cheat-sheet) |

What you cannot do in plain markdown is put block elements in a cell: no headings, no multi-paragraph text, no bulleted lists and no code blocks. A table row is one line of source, so a cell is one line of content. Many renderers accept an inline <br> tag to fake a line break, but that depends on the app allowing inline HTML, so test it before relying on it.

Showing a pipe character

A pipe inside a cell would be read as a column boundary. Escape it with a backslash:

| Operator | Meaning |
| --- | --- |
| `a \| b` | a or b |

The escape works even inside inline code in GitHub Flavored Markdown, though some other renderers differ. If you see an extra column appear, a stray pipe is almost always the cause.

A worked example: comparing options

Tables are at their best for short, regular comparisons. Here is a note you might keep when choosing a tool:

| Option | Storage | Offline | Export |
| :----- | :------ | :-----: | :----- |
| App A  | Local   | Yes     | PDF    |
| App B  | Cloud   | Partial | DOCX   |
| App C  | Local   | Yes     | HTML   |

Keep the column count small, keep cells to a few words, and put the thing you will scan by in the first column. If you are doing this kind of evaluation, the markdown note-taking app checklist gives you criteria worth turning into columns.

Common mistakes and how to fix them

Symptom	Likely cause	Fix
Table shows as plain text	Missing separator row	Add a line of dashes under the header
Table shows as plain text	No blank line above it	Leave an empty line before the header row
Extra or missing column	Unescaped pipe in a cell	Write `\\|`
Header and body disagree	Different column counts	Match the number of cells in every row
Alignment ignored	Renderer limitation or typo in colons	Check the separator row; test in another preview

The blank line above the table is the one people miss most. Without it, some renderers treat the header as a continuation of the paragraph before it.

Editing wide tables

Raw tables become awkward once they pass five or six columns or contain long cells. Two habits help. First, pad cells so the pipes line up while you edit, which makes it obvious when a row is missing a cell. Second, if a table is only a data dump, consider keeping it in a spreadsheet and pasting a small summary into your note. Markdown is for readable text, and a 20-column table is not readable in source form.

When not to use a table

Skip the table if you need merged cells, cells with several paragraphs, or nested lists inside cells. None of those are possible in plain markdown. A heading with a list under it usually reads better for items that each have a lot of detail. Tables also work poorly for a simple list of two-part items, such as a glossary; a bulleted list with bold terms is easier to maintain. Finally, tables are hard to read on narrow screens in some renderers, so for content that will be read in many places, keep them short.

Exporting tables

If a note with a table is going into a Word document or PDF, check the rendered preview first, since a malformed table will be exported as plain text. atiea exports notes to Markdown, HTML, PDF and DOCX; see how to convert markdown to PDF or Word on Mac for tips on getting clean output. Keep tables simple and the exported result will be too.

Try it in a notes app

Type the examples above into a note in the atiea markdown editor, which highlights markdown as you type, so you can see a mistake as soon as you make it. For every other piece of syntax, see the markdown cheat sheet, and for the file format itself read what an MD file is. You can also browse the atiea feature list to see what else the app offers for writing and organizing notes.