Markdown Table Syntax

Basic Table Syntax

A Markdown table uses pipes (|) and hyphens (-) to define columns and rows:

| Name    | Role       | Location  |
|---------|------------|-----------|
| Alice   | Engineer   | Berlin    |
| Bob     | Designer   | Tokyo     |
| Charlie | PM         | New York  |

Rules:

• The first row is always the header
• The second row (with hyphens) separates the header from data
• Each column is separated by a pipe |
• Leading and trailing pipes are optional but recommended for readability
• Columns don’t need to be perfectly aligned in the source — the renderer handles spacing

Column Alignment

Control text alignment in each column using colons (:) in the separator row:

| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| Text         | Text           | Text          |
| More text    | More text      | 1,234.56      |

• :--- or --- — left-aligned (default)
• :---: — center-aligned
• ---: — right-aligned

Right alignment is useful for numeric columns — prices, counts, percentages. Center alignment works well for status indicators or short labels.

Formatting Inside Tables

You can use inline Markdown formatting inside table cells:

| Feature    | Status          | Notes                     |
|------------|-----------------|---------------------------|
| Dark mode  | **Done**        | Shipped in v1.3           |
| Export PDF | ~~Cancelled~~   | Use `Cmd+Shift+E` instead |
| Search     | *In progress*   | [Tracking issue](#)       |

Supported formatting:

• Bold — **text**
• Italic — *text*
• Code — `text`
• Strikethrough — ~~text~~
• Links — [text](url)
• Images — ![alt](url) (though images in tables can be tricky to size)

Not supported in standard Markdown tables:

• Headings (#)
• Block quotes (>)
• Lists (- or 1.)
• Multi-line content (each cell must be on one line)
• Cell merging (rowspan/colspan)

Escaping Pipes in Tables

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

| Command         | Description           |
|-----------------|-----------------------|
| `a \| b`        | Logical OR            |
| `grep "error"`  | Search for errors     |

Without the backslash, the pipe would be interpreted as a column separator.

Minimal Tables

You can write very compact tables if readability isn’t a priority:

Name|Role
-|-
Alice|Engineer
Bob|Designer

This is valid Markdown and renders the same way. However, aligned tables are much easier to read and maintain in source files.

Multi-line Cells

Standard Markdown tables don’t support line breaks inside cells. Each cell must be a single line. To add multiple lines within a cell, use an HTML <br> tag:

| Method     | Pros                          | Cons                  |
|------------|-------------------------------|-----------------------|
| Native app | Fast launch<br>Low memory     | macOS only            |
| VS Code    | Extensions<br>Built-in terminal | Slow startup<br>Heavy |

<br> tags work on GitHub, GitLab, and most Markdown renderers. Some strict parsers may not support them — test before relying on this in production docs.

Rowspan and Colspan in Markdown

Standard Markdown tables do not support cell merging — there is no native rowspan or colspan syntax. Every row must have the same number of columns.

If you need merged cells, use inline HTML instead of Markdown table syntax:

<table>
  <tr>
    <th>Name</th>
    <th colspan="2">Contact</th>
  </tr>
  <tr>
    <td>Alice</td>
    <td>alice@example.com</td>
    <td>+1 555-0100</td>
  </tr>
  <tr>
    <td rowspan="2">Team B</td>
    <td>bob@example.com</td>
    <td>+1 555-0200</td>
  </tr>
  <tr>
    <td>charlie@example.com</td>
    <td>+1 555-0300</td>
  </tr>
</table>

Important: GitHub strips some HTML table attributes in certain contexts (issues, comments). HTML tables work reliably in .md files rendered in the repository view. For maximum compatibility, stick to flat Markdown tables without merging.

README Table Examples

README files on GitHub commonly use tables for feature lists, badges, and API docs. Here are copy-paste templates:

Feature Comparison Table

| Feature       | Free | Pro  |
|---------------|:----:|:----:|
| Basic editing | ✓    | ✓    |
| Export to PDF | ✗    | ✓    |
| API access    | ✗    | ✓    |

API Endpoint Table

| Method   | Endpoint         | Description    |
|----------|------------------|----------------|
| `GET`    | `/api/users`     | List all users |
| `POST`   | `/api/users`     | Create a user  |
| `DELETE` | `/api/users/:id` | Delete a user  |

GitHub Flavored Markdown Tables

GitHub, GitLab, and most modern Markdown renderers use the GFM (GitHub Flavored Markdown) table spec. This is the syntax described on this page.

Some platforms extend GFM with extras:

• GitHub — supports standard GFM tables, no extensions
• GitLab — same as GitHub
• Obsidian — supports multi-line cells with <br> tags
• Notion — uses its own table format, not standard Markdown

If you’re writing for GitHub (README.md, issues, PRs), the standard syntax on this page is all you need.

Common Mistakes

Missing separator row:

| Name  | Role     |
| Alice | Engineer |

Without the |---|---| row, this won’t render as a table — it will appear as plain text with pipes.

Inconsistent column count:

| Name  | Role     | Location |
|-------|----------|
| Alice | Engineer | Berlin   |

The separator row has 2 columns but the header has 3. Most renderers will still try, but the result may look broken.

Trailing spaces before pipes:
Some editors add trailing spaces that can break rendering in strict parsers. If your table looks wrong, check for extra whitespace.

Tools for Creating Markdown Tables

If you’re working with large tables, typing pipes by hand gets tedious. These tools help:

• TableConvert.io — paste CSV, Excel, or HTML and get Markdown table output
• VS Code — the Markdown All in One extension adds table formatting shortcuts
• Pandoc — convert CSV to Markdown: pandoc input.csv -t markdown -o output.md
• MDViewer — preview your table rendering in real time as you type

Viewing Markdown Tables

Raw Markdown tables in a text editor can be hard to read, especially with many columns. A dedicated Markdown viewer renders them as properly formatted HTML tables with borders, alignment, and styling.

MDViewer is a native macOS app that renders GitHub Flavored Markdown — including tables with alignment, inline formatting, and syntax highlighting. Open any .md file from Finder and see the table rendered instantly. Currently free for early adopters — a Pro tier is planned, but early users get the full app at no cost.

FAQ

How many columns can a Markdown table have?
There’s no official limit. Practically, more than 6–8 columns becomes hard to read in source and in rendered output. For very wide data, consider using a CSV file or a dedicated table tool instead.

Can I merge cells in a Markdown table?
Standard Markdown doesn’t support rowspan or colspan. If you need merged cells, use inline HTML: <td rowspan="2">. However, many Markdown renderers (including GitHub) will strip HTML tables in certain contexts.

How do I make a Markdown table from a spreadsheet?
Copy the cells from Excel or Google Sheets, paste into TableConvert.io, and select Markdown output. Alternatively, export as CSV and convert with Pandoc.

Can I sort a Markdown table?
Not in the Markdown source itself — tables are static. Some Markdown viewers render tables with sortable headers, but this is not standard behavior.

Try MDViewer

MDViewer is currently free for early adopters — all features included. Download it and see if it fits your workflow.

Requires macOS 13.0 or later. Intel and Apple Silicon.