How to Make a Table in Markdown (With Examples)

To make a table in Markdown, separate your column headers with pipe characters (|), then add a divider row of dashes (---) under the headers, and put each row of data on its own line with pipes between the cells. That divider row is what turns plain text into a rendered table. Here is the smallest working example:

| Name  | Role     |
| ----- | -------- |
| Mezi  | Founder  |
| Luang | Engineer |

That renders as a two-column table with a bold header row. The rest of this guide covers the exact syntax, column alignment, how tables behave on GitHub and in a README, the limits you will hit, and a faster way to build big tables from spreadsheet data.

Markdown table syntax explained (pipes and dashes)

A Markdown table has three parts, and all three are required.

1. Header row. The text for each column, wrapped in pipes: | Name | Role |.
2. Divider row. At least three dashes per column: | --- | --- |. This line tells the parser “the row above is a header, everything below is data.”
3. Data rows. One line per row, same pipe pattern as the header.

The outer pipes at the start and end of each line are optional in most parsers, so Name | Role works too. Adding them back makes the raw text line up in your editor and is worth the few extra keystrokes. The dashes in the divider do not need to match the width of your text either. | --- | and | --------- | render identically. People pad them only so the source looks tidy.

Spacing inside cells is trimmed, so you do not have to align columns perfectly by hand. |Name|Role| and | Name | Role | produce the same output. If you want a deeper reference on the surrounding formatting rules, the markdown syntax guide covers headings, lists, and emphasis that pair with tables.

How to create a table in Markdown step by step

Here is how to create a table in Markdown from a blank line, one step at a time.

Step 1: Write the header. Decide your columns and type them with pipes.

| Task | Status | Owner |

Step 2: Add the divider. Match the number of columns with dashed cells.

| ---- | ------ | ----- |

Step 3: Add your rows. Each row needs the same number of pipes as the header.

| Ship v1     | Done        | Mezi  |
| Write docs  | In progress | Luang |

Put it together and you get a clean three-column table. The one rule that trips people up: every data row must have the same column count as the header. If your header has three columns and a row has two, the row renders short and the layout breaks. Count the pipes if a table looks wrong.

Adding and aligning columns

You add a column by adding one more cell to the header, one more dashed cell to the divider, and one more cell to every data row. Miss any of those three and the table misaligns.

Alignment is controlled entirely in the divider row using colons:

| Left     | Center   | Right    |
| :------- | :------: | -------: |
| default  | middle   | numbers  |
| text     | label    | 1,299    |

• :--- aligns the column left (this is also the default).
• :---: centers it.
• ---: aligns it right.

Right alignment is the practical one. Put numbers, prices, and counts in a right-aligned column so the digits line up by place value and are easy to scan. For a full walkthrough of every alignment case, including how different renderers treat mixed content, see markdown table alignment.

Tables in GitHub Flavored Markdown and READMEs

GitHub Flavored Markdown (GFM) uses the exact syntax above, so a table you write here works in a README, a pull request comment, or an issue with no changes. Tables are one of the extensions GFM adds on top of plain CommonMark, which does not include table support at all. That is why the same table can render on GitHub but show as raw pipes on a platform that only supports base Markdown.

A README table is the most common real use. A short feature or comparison table near the top of a repo reads far better than a bullet list:

| Feature        | Free | Pro |
| -------------- | :--: | :-: |
| CSV import     | Yes  | Yes |
| Custom exports | No   | Yes |

Keep README tables narrow. GitHub does not wrap wide tables gracefully, so a table with eight columns will force horizontal scrolling on smaller screens. If you find yourself needing that many columns, that is usually a sign the data wants a different shape, and it is worth asking whether Markdown is the right tool. The markdown vs html comparison goes into when to reach for a raw HTML table instead.

Formatting inside cells: bold, links, and code

You can format text inside a cell with normal inline Markdown. Bold with **text**, italics with *text*, inline code with backticks, and links with [label](url) all work:

| Item     | Note                                   |
| -------- | -------------------------------------- |
| **Name** | use `PascalCase`                       |
| Docs     | see the [guide](https://example.com)   |

The one character that needs care is the pipe itself. A literal | inside a cell will be read as a column separator and break the row. Escape it with a backslash: write a \| b to show “a | b” in a cell. Inline code spans do not protect pipes in every parser, so escaping is the safe habit.

Limitations of Markdown tables (no merged cells, no line breaks)

Markdown tables are deliberately simple, and that simplicity has hard limits. Knowing them up front saves you from fighting the syntax.

• No merged or spanning cells. There is no colspan or rowspan. Every cell is its own box.
• No real line breaks inside a cell. You cannot press Enter mid-cell. On GitHub you can insert a <br> tag to force a break, but plain Markdown has no native way to do it.
• No nested tables. A table cannot contain another table.
• No block elements in cells. Lists, headings, and code fences do not work inside a cell. Only inline formatting does.
• No control over column width. Widths are decided by the renderer based on content.

When you need any of those, an HTML <table> is the honest answer, and it works inside most Markdown files because Markdown lets you drop raw HTML in. You trade the clean, readable source for full control.

Faster option: convert CSV or spreadsheet data to a Markdown table

Hand-typing pipes is fine for a five-row table. It is miserable for fifty rows, and it is error-prone the moment your data already lives in a spreadsheet. If your data is in Excel, Google Sheets, or a .csv file, do not retype it.

Paste the data into our free CSV to Markdown converter and it builds the full table for you, divider row and all, with the columns already aligned. Copy the output straight into your README or post.

The workflow that saves the most time: keep the source data in a sheet, edit it there where sorting and formulas are easy, then re-export to Markdown whenever you need to update the published table. You get a clean table without counting a single pipe.

Troubleshooting: why your table isn’t rendering

If your table shows as a row of raw pipes instead of a grid, one of these is almost always the cause:

• Missing divider row. No | --- | line under the header means no table. This is the number one reason.
• Blank line missing above the table. Some parsers need an empty line between a paragraph and the start of a table.
• Mismatched column counts. A data row with more or fewer cells than the header can break the layout.
• Unescaped pipe in a cell. A stray | splits a cell into two. Escape it as \|.
• Platform without table support. Base CommonMark has no tables. If the same table renders on GitHub but not elsewhere, the target platform likely does not support GFM tables.

FAQ

Do I need the outer pipes at the start and end of each row? No. Most parsers, including GitHub’s, accept rows without the leading and trailing pipes. Keeping them makes the raw source easier to read, so it is a good habit rather than a requirement.

How do I add a line break inside a Markdown table cell? Plain Markdown has no native way to do it. On GitHub and other GFM platforms you can insert a <br> tag where you want the break. If you need multi-line, formatted content in a cell, use a raw HTML table instead.

Why is my Markdown table not showing as a table? The most common cause is a missing divider row of dashes under the header. Check that the divider exists, that every row has the same number of columns, and that the platform actually supports Markdown tables (base CommonMark does not).

What is the fastest way to make a large Markdown table? Do not type it by hand. Keep the data in a spreadsheet or CSV and run it through a CSV to Markdown converter, which generates the pipes, divider, and alignment for you in one step.