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 | WriterColumn 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.