Markdown Table Syntax: The Complete Guide (with Examples and a Generator)

Markdown Tables: Easy to Read, Painful to Write

A Markdown table is one of the nicest things to read in a README and one of the most tedious things to type. The syntax itself is simple: a few pipes, a row of dashes, done. But as soon as a table has more than three columns, you’re counting spaces, re-aligning pipes after every edit and hunting for the one row that’s missing a cell.

This guide covers everything you need to know about Markdown table syntax: the basics, alignment, formatting inside cells, how platforms like GitHub, GitLab, Notion and Obsidian differ, where Markdown tables hit their limits, and how to skip the manual work with a Markdown table generator. There’s a cheat sheet at the end you can bookmark.

Basic Markdown Table Syntax

A Markdown table has three parts:

1. A header row, with column names separated by pipes (|).
2. A separator row, with dashes (-) for every column. This is what turns plain text into a table.
3. Body rows, one line per row, cells separated by pipes.

Here’s a minimal example:

| Name  | Role      | Location |
| ----- | --------- | -------- |
| Alice | Developer | Berlin   |
| Bob   | Designer  | Lisbon   |

Which renders as:

Name	Role	Location
Alice	Developer	Berlin
Bob	Designer	Lisbon

A few rules worth knowing:

• The header row is required. In GitHub Flavored Markdown (GFM), the spec most platforms follow, there’s no such thing as a table without a header.
• The separator row needs at least one dash per column. Three dashes (---) is the common convention.
• Outer pipes are optional. Name | Role works just as well as | Name | Role |, but the outer pipes make tables easier to read and are less error-prone.
• Columns don’t have to line up. The padding spaces are only there for humans. This is a perfectly valid table:

| Name | Role | Location |
|---|---|---|
| Alice | Developer | Berlin |
| Bob | Designer | Lisbon |

• Every row should have the same number of cells as the header. In GFM, missing cells are rendered empty and extra cells are dropped, but other renderers may be less forgiving.
• Leave a blank line before the table. Otherwise some renderers treat it as part of the previous paragraph.

Aligning Columns

You control the alignment of each column with colons in the separator row:

Syntax	Alignment
---	Default (usually left)
:---	Left
:---:	Center
---:	Right

Here are all three side by side:

| Left aligned | Centered | Right aligned |
| :----------- | :------: | ------------: |
| Apples       |    12    |         $1.20 |
| Bananas      |    7     |         $0.85 |
| Cherries     |   150    |        $12.40 |

Left aligned	Centered	Right aligned
Apples	12	$1.20
Bananas	7	$0.85
Cherries	150	$12.40

Right alignment is the one you’ll want most often for numbers, prices and dates, so the digits line up.

Formatting Inside Table Cells

Most inline Markdown works inside table cells:

| Feature        | Example                                  |
| -------------- | ---------------------------------------- |
| Bold           | **important**                            |
| Italic         | _emphasis_                               |
| Strikethrough  | ~~removed~~                              |
| Link           | [Table Generator](https://www.table-generator.com) |
| Inline code    | `npm install`                            |
| Escaped pipe   | `a \| b`                                 |
| Line break     | First line<br>Second line                |

Feature	Example
Bold	important
Italic	emphasis
Strikethrough	removed
Link	Table Generator
Inline code	npm install
Escaped pipe	a | b
Line break	First line Second line

Two things trip people up:

• Pipes inside a cell must be escaped as \|. Otherwise the pipe is read as a column separator and your row breaks. This applies inside inline code too, as the “Escaped pipe” row above shows.
• There’s no Markdown syntax for a line break inside a cell. A table row has to be a single line. The workaround is the HTML tag <br>, which works on GitHub, GitLab and most renderers that allow inline HTML.

Block-level elements don’t work inside cells: no headings, no lists, no code blocks, no blockquotes. If you need those, you need an HTML table (more on that below).

Markdown Tables on Different Platforms

Tables aren’t part of the original Markdown specification. They were added later by “flavors” like GitHub Flavored Markdown, which is why support varies from platform to platform.

Platform	Markdown tables	Notes
GitHub	Yes	Full GFM support, including alignment and <br> in cells
GitLab	Yes	Same syntax as GitHub; also supports <br> in cells
Bitbucket	Yes	Standard pipe syntax
Stack Overflow	Yes	GFM-style tables in questions and answers
Obsidian	Yes	Escape the pipe in aliased links: [[Page|Alias]]
Notion	Partly	No Markdown editing, but pasting a Markdown table creates a table
Reddit	Yes	Works in the Markdown editor; the rich text editor has a table button
Jira / Confluence	No	Jira wiki markup uses its own syntax: ||Header|| and |Cell|
Slack, Discord, WhatsApp	No	Pipes are shown as plain text

GitHub and GitLab

GitHub is where most people meet Markdown tables, in READMEs, issues, pull requests and wikis. GitHub follows the GFM spec exactly, so everything in this guide works there. GitLab’s own flavor (GLFM) uses the same syntax, so a table you write for one will render on the other.

Notion and Obsidian

Obsidian stores notes as plain Markdown files, so tables work exactly as described here. Its one quirk: internal links with an alias, like [[Page|Alias]], contain a pipe, so inside a table you have to write [[Page\|Alias]].

Notion doesn’t let you type Markdown tables directly, but when you paste a Markdown table into a page, Notion usually converts it into a native table. That makes a generated Markdown table a handy way to move data into Notion.

Where Markdown Tables Don’t Work

Chat apps like Slack, Discord and WhatsApp support some Markdown formatting, but not tables. Your pipes will show up as plain text. The usual workaround is to wrap the table in a code block, so at least the columns stay aligned in a monospace font, or to share the table as an image instead. Jira and Confluence use their own wiki markup and editors, so it’s usually easier to paste table data from a spreadsheet or use their table tools.

Limitations of Markdown Tables

Markdown tables are deliberately simple. That’s great for small data, but you’ll eventually run into these limits:

• No merged cells. There’s no colspan or rowspan. Every row has exactly one cell per column.
• No multi-line cells. Each row has to fit on one line. <br> gives you visual line breaks, but no paragraphs, lists or code blocks.
• No captions. There’s no syntax to attach a caption or title to a table. Use a heading or a paragraph above it instead.
• No styling. No column widths, colors, borders or striped rows. How the table looks is entirely up to the platform’s stylesheet.
• A header row is mandatory. You can’t create a table without one (a common workaround is an empty header, which looks odd on most platforms).
• Large tables are hard to maintain. A table with ten columns and long cell values quickly becomes unreadable in the source file.

When you hit these limits and the platform allows HTML, switch to an HTML table. GitHub, GitLab and most static site generators render raw <table> markup inside Markdown files:

<table>
  <thead>
    <tr><th>Quarter</th><th colspan="2">Revenue</th></tr>
  </thead>
  <tbody>
    <tr><td>Q1</td><td>$10,000</td><td>+5%</td></tr>
  </tbody>
</table>

If you want a styled, responsive HTML table for a website rather than a README, Table Generator can export that too, either as plain HTML or as an embeddable Web Component.

The Fast Way: Generate Markdown Tables

Writing a Markdown table by hand is fine for three rows. For anything larger, or anything you’ll edit later, it’s much faster to build the table visually and let a generator take care of pipes, padding and separator rows.

Here’s how it works with Table Generator:

1. Open the generator. You’ll start with a sample table. Click “Clear Table” in the top right corner to start from scratch.
2. Add your columns and rows with the plus buttons, and click into any cell to type or paste its content. Use the dropdown in a column header to insert or remove columns at a specific position.
3. Choose the alignment. Turn on “Center” in the “Cells” section of the sidebar to get centered columns (:---:) in the Markdown output.
4. Click “Export Table” and select the “Markdown” tab. Your table appears as neatly padded Markdown, with every pipe lined up. Click “Copy to Clipboard” and paste it into your README, issue, wiki or notes.

Because the generator keeps your table as structured data, you can come back, change a value or add a column, and export again without re-aligning anything by hand. And the same table can be exported as HTML, PNG, SVG, PDF or CSV whenever Markdown isn’t an option.

Converting CSV, Excel and HTML to Markdown

Already have your data somewhere else? Here’s how to get it into a Markdown table.

CSV to Markdown

For small CSV files, the quickest way is to copy the values into the generator and export as Markdown. For larger files or scripts, Pandoc can convert CSV directly:

pandoc data.csv -f csv -t gfm -o table.md

The first line of the CSV becomes the header row.

Excel and Google Sheets to Markdown

Spreadsheets don’t export Markdown on their own. The most reliable route is to save the sheet as CSV first (in Excel: File → Save As → CSV; in Google Sheets: File → Download → Comma-separated values) and then convert the CSV as shown above. For a handful of rows, copying the cells into the generator is usually faster.

HTML to Markdown

To turn an existing HTML table into Markdown, Pandoc works here too:

pandoc table.html -f html -t gfm -o table.md

Keep in mind that Markdown can’t represent everything HTML can. Merged cells, nested lists or multiple paragraphs in a cell can’t be converted to a pipe table, and Pandoc will keep such tables as raw HTML instead.

Markdown Table Cheat Sheet

Copy this block and keep it around. It covers everything you’ll need day to day:

<!-- Basic table: header row, separator row, body rows -->
| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell     | Cell     | Cell     |

<!-- Alignment: left, center, right -->
| Left | Center | Right |
| :--- | :----: | ----: |
| a    |   b    |     c |

<!-- Formatting inside cells -->
| Syntax         | Result                    |
| -------------- | ------------------------- |
| **bold**       | Bold text                 |
| _italic_       | Italic text               |
| `code`         | Inline code               |
| [link](url)    | Link                      |
| a \| b         | Literal pipe character    |
| line 1<br>line 2 | Line break inside a cell |

<!-- Rules -->
<!-- 1. A header row is required.                          -->
<!-- 2. At least one dash per column in the separator row. -->
<!-- 3. Outer pipes and aligned columns are optional.      -->
<!-- 4. Leave a blank line before the table.               -->
<!-- 5. No merged cells or block content: use HTML.        -->

FAQ

How do I make a table in Markdown?

Write a header row with column names separated by pipes (| Name | Role |), add a separator row with dashes for each column (| --- | --- |), then add one line per row of data. Or build the table visually with a Markdown table generator and copy the result.

How do I align text in a Markdown table?

Add colons to the separator row: :--- for left, :---: for center and ---: for right alignment. The alignment applies to the whole column, including the header.

How do I add a line break in a Markdown table cell?

Use the HTML tag <br>, for example First line<br>Second line. Markdown itself has no syntax for line breaks inside table cells.

How do I use a pipe character inside a table cell?

Escape it with a backslash: \|. This also applies inside inline code.

Can I merge cells in a Markdown table?

No. Markdown tables don’t support colspan or rowspan. If you need merged cells, use an HTML table instead.

Does GitHub support Markdown tables?

Yes. GitHub Flavored Markdown supports tables in READMEs, issues, pull requests, comments and wikis, including column alignment and <br> line breaks.

Is there a Markdown table generator?

Yes. Table Generator is a free, browser-based editor that lets you build a table visually and export it as Markdown, HTML, PNG, SVG, PDF or CSV. Everything runs in your browser, no sign-up required.

Create Your Markdown Table Now

Stop counting pipes and re-aligning columns. Open the Markdown table generator, build your table visually and copy clean, perfectly aligned Markdown in seconds. New here? Read the introduction to Table Generator to see everything it can do.