Markdown Tables: How to Create Tables in Markdown

Tables are one of the most useful features in Markdown for organizing data. Whether you need a comparison table, a pricing grid, or an API reference, a table in Markdown keeps your content structured and easy to read.

This guide covers everything from basic table markdown syntax to advanced formatting techniques.

Basic Table Syntax

A markdown table uses pipes (|) to separate columns and hyphens (-) to create the header row:

| Name    | Role      | Location |
| ------- | --------- | -------- |
| Alice   | Developer | London   |
| Bob     | Designer  | Berlin   |
| Charlie | Manager   | Tokyo    |

Result:

Name	Role	Location
Alice	Developer	London
Bob	Designer	Berlin
Charlie	Manager	Tokyo

Key rules:

• The first row is always the header
• The second row (separator) requires at least three hyphens per column
• Outer pipes are optional but recommended for readability
• Columns don't need to be perfectly aligned in the source

This minimal version also works:

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

Column Alignment

Control text alignment in each column by adding colons to the separator row:

| Left Aligned | Center Aligned | Right Aligned |
| :----------- | :------------: | ------------: |
| Text         |     Text       |          Text |
| More text    |   More text    |     More text |

Result:

Left Aligned	Center Aligned	Right Aligned
Text	Text	Text
More text	More text	More text

Alignment rules:

• :--- or --- for left alignment (default)
• :---: for center alignment
• ---: for right alignment

Right alignment works well for numbers and prices. Center alignment is useful for status indicators or short labels.

Step-by-Step Guide to Creating a Markdown Table

1. Define Your Headers

Start with a pipe-separated list of column names:

| Product | Price | Rating |

2. Add the Separator Row

Add a row of hyphens below the header. Include colons for alignment:

| Product | Price | Rating |
| :------ | ----: | :----: |

3. Add Your Data Rows

Fill in each row with pipe-separated values:

| Product | Price | Rating |
| :------ | ----: | :----: |
| Widget  | $9.99 |  4.5   |
| Gadget  | $24.99|  4.8   |

4. Review and Align

Clean up spacing so columns line up visually. This is optional but makes the source easier to read:

| Product | Price  | Rating |
| :------ | -----: | :----: |
| Widget  |  $9.99 |  4.5   |
| Gadget  | $24.99 |  4.8   |

Common Table Examples

Comparison Table

| Feature       | Free Plan | Pro Plan   | Enterprise |
| :------------ | :-------: | :--------: | :--------: |
| Storage       |    1 GB   |   50 GB    | Unlimited  |
| Users         |     1     |     10     | Unlimited  |
| Support       |   Email   | Priority   | Dedicated  |
| Custom Domain |    No     |    Yes     |    Yes     |

Pricing Table

| Plan       | Monthly | Annual  | Savings |
| :--------- | ------: | ------: | ------: |
| Starter    |   $9/mo |  $7/mo  |    22%  |
| Pro        |  $29/mo | $24/mo  |    17%  |
| Business   |  $99/mo | $79/mo  |    20%  |

Feature Matrix

| Feature        | macOS | Windows | Linux |
| :------------- | :---: | :-----: | :---: |
| Dark Mode      |  Yes  |   Yes   |  Yes  |
| Auto-update    |  Yes  |   Yes   |  No   |
| CLI Support    |  Yes  |   Yes   |  Yes  |
| GPU Accel.     |  Yes  |   Yes   | Partial|

API Reference Table

| Endpoint         | Method | Description            | Auth Required |
| :--------------- | :----- | :--------------------- | :-----------: |
| `/users`         | GET    | List all users         |      Yes      |
| `/users/:id`     | GET    | Get user by ID         |      Yes      |
| `/users`         | POST   | Create a new user      |      Yes      |
| `/auth/login`    | POST   | Authenticate user      |      No       |

Formatting Inside Tables

You can use inline Markdown formatting within table cells.

Bold and Italic

| Syntax       | Output       |
| ------------ | ------------ |
| `**bold**`   | **bold**     |
| `*italic*`   | *italic*     |
| `***both***` | ***both***   |

Inline Code

| Command        | Description        |
| -------------- | ------------------ |
| `git status`   | Check file changes |
| `git commit`   | Save changes       |
| `git push`     | Upload to remote   |

Links in Tables

| Resource                          | Description     |
| --------------------------------- | --------------- |
| [MDN Docs](https://developer.mozilla.org) | Web reference   |
| [Can I Use](https://caniuse.com)  | Browser support |

Escaping Pipes

If your cell content contains a literal pipe character, escape it with a backslash:

| Expression   | Result |
| ------------ | ------ |
| `a \| b`     | a | b  |

Multi-line Content in Table Cells

Standard Markdown does not support line breaks inside table cells. Use the HTML <br> tag to force a new line:

| Name  | Address                                   |
| ----- | ----------------------------------------- |
| Alice | 123 Main St<br>Suite 4<br>London, UK      |
| Bob   | 456 Oak Ave<br>Apt 7B<br>Berlin, Germany  |

Result:

Name	Address
Alice	123 Main St<br>Suite 4<br>London, UK
Bob	456 Oak Ave<br>Apt 7B<br>Berlin, Germany

For longer content, consider using an HTML table instead. Markdown tables are best suited for short, concise data.

Tables in Different Markdown Processors

Not all Markdown processors handle tables the same way. Here is a quick compatibility overview:

Processor	Tables Supported	Alignment	HTML in Cells
GitHub (GFM)	Yes	Yes	Yes
GitLab	Yes	Yes	Yes
Obsidian	Yes	Yes	Yes
Jekyll (kramdown)	Yes	Yes	Yes
Hugo	Yes	Yes	Yes
CommonMark	No	No	N/A
Pandoc	Yes	Yes	Yes

Key notes:

• GitHub Flavored Markdown (GFM) is the most common standard and supports all table features covered here.
• CommonMark does not include table syntax in the core spec. Extensions are needed.
• Obsidian renders tables well and includes a built-in table editor for easier formatting.
• Jekyll uses kramdown by default, which supports tables and additional features like row spans.

If your target processor does not support Markdown tables, fall back to HTML <table> elements.

Tips and Best Practices

Keep Columns Narrow

Wide tables break on small screens. Aim for short cell content:

<!-- Avoid -->
| This is a very long column header that will cause problems | Another long one |

<!-- Better -->
| Header   | Header 2 |

Use a Table Formatter

Manually aligning pipes is tedious. Use a tool to format your tables:

• Prettier with the Markdown plugin auto-formats tables
• VS Code extensions like "Markdown Table Formatter" align columns on save
• Online tools like TableConvert or Markdown Tables Generator create tables from spreadsheet data

Test Your Rendering

Always preview your table in the target platform. What looks correct in your editor may render differently on GitHub, your blog, or a documentation site.

Consider Alternatives for Complex Data

If you need any of the following, use HTML tables instead:

• Merged cells (colspan or rowspan)
• Nested tables
• Cells with multiple paragraphs
• Row or column highlighting

Accessibility

Add clear, descriptive headers. Screen readers use the header row to describe each cell's context to visually impaired users.

Related Guides

This post is part of our Markdown series. Check out the other guides:

• Markdown Footnotes: How to Add Footnotes in Markdown
• How to Add Images in Markdown: Complete Guide