Markdown Tables — Syntax, Examples & Templates

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.

Markdown Table Without a Header

Standard Markdown requires a header row — there is no way to create a headerless table using pipe-and-hyphen syntax. The first row is always treated as the header, and the separator row (|---|) is mandatory.

If you need a table without a visible header, use one of these workarounds:

Empty Header Cells

|       |          |
|-------|----------|
| Alice | Engineer |
| Bob   | Designer |

This renders a table with an empty-looking header. The header row still exists in the HTML, but it appears blank. Most renderers (including GitHub) handle this correctly.

HTML Table Without a Header

For a truly headerless table, use raw HTML:

<table>
  <tr><td>Alice</td><td>Engineer</td></tr>
  <tr><td>Bob</td><td>Designer</td></tr>
</table>

This gives you a clean table with no header at all. Works on GitHub, GitLab, and any renderer that supports inline HTML.

Lists and Nested Content in Table Cells

Standard Markdown tables don’t support block-level elements like lists, blockquotes, or paragraphs inside cells. Each cell is limited to a single line of inline content.

To work around this, you have two options:

Line Breaks with <br>

Simulate a list with line breaks and bullet characters:

| Tool     | Features                                                    |
|----------|-------------------------------------------------------------|
| MDViewer | &bull; GFM tables<br>&bull; Mermaid diagrams<br>&bull; Syntax highlighting |
| TextEdit | &bull; Plain text only                                       |

HTML Table with Real Lists

For actual nested lists, use HTML:

<table>
  <tr>
    <th>Tool</th>
    <th>Features</th>
  </tr>
  <tr>
    <td>MDViewer</td>
    <td>
      <ul>
        <li>GFM tables</li>
        <li>Mermaid diagrams</li>
        <li>Syntax highlighting</li>
      </ul>
    </td>
  </tr>
</table>

HTML tables with lists work on GitHub repository pages, but may be stripped in issues and comments. For a quick check of how your table renders, open the .md file in a Markdown viewer.

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 for GitHub

README files on GitHub commonly use tables for feature lists, badges, installation instructions, and API docs. Here are copy-paste templates you can use right away. For more README patterns, see our README.md template guide.

Feature Comparison Table

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

Installation / Platform Table

| Platform | Install Command          | Min Version    |
|----------|--------------------------|----------------|
| macOS    | `brew install myapp`     | 13.0+          |
| Linux    | `apt install myapp`      | Ubuntu 22.04+  |
| Windows  | `winget install myapp`   | Windows 10+    |

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  |

Keyboard Shortcuts Table

| Action         | macOS          | Windows / Linux  |
|----------------|----------------|------------------|
| Save           | `⌘S`           | `Ctrl+S`         |
| Find           | `⌘F`           | `Ctrl+F`         |
| Toggle preview | `⌘Shift+P`     | `Ctrl+Shift+P`   |

GitHub Markdown Tables

GitHub uses the GFM (GitHub Flavored Markdown) table spec everywhere — README files, issues, pull requests, discussions, and wiki pages. The pipe-and-hyphen syntax described on this page is all you need.

What Works on GitHub

• Standard pipe tables with alignment (this page’s syntax)
• Inline formatting: bold, italic, code, strikethrough, links
• <br> for line breaks inside cells
• HTML tables (in repository files only — stripped in issues/comments)

What Doesn’t Work on GitHub

• colspan / rowspan — GitHub’s Markdown processor strips these attributes from HTML tables in most contexts
• Nested lists in cells — use <br> with bullet characters (•) instead
• Table captions — no native support; add a bold line above the table as a workaround
• Cell background colors — CSS is stripped; use emoji or text indicators instead

Table Support Across Platforms

* GitHub allows HTML tables in repository .md files but strips most HTML from issues, comments, and discussions.

If you’re writing for GitHub (README.md, issues, PRs), the standard syntax on this page is all you need. For the full Markdown cheat sheet — including headings, lists, links, and images — see our companion guide.

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.

Markdown Table Generators & Converters

Typing pipes by hand works for small tables, but for anything beyond 3×3 it gets tedious. These tools convert existing data into Markdown table syntax:

Online Generators

• TableConvert.io — paste CSV, Excel, JSON, or HTML and get Markdown output. Supports alignment settings and lets you switch between formats
• Tables Generator (tablesgenerator.com) — visual editor with a spreadsheet-like interface. Build your table by clicking, then copy the Markdown

Command-Line Tools

• Pandoc — convert between formats: pandoc data.csv -t gfm -o table.md
• csvtomd — lightweight CSV-to-Markdown converter: csvtomd data.csv

Editor Integrations

• VS Code — the Markdown All in One extension adds table formatting (Alt+Shift+F) and auto-completion for pipes
• MDViewer — preview your table rendering in real time as you type. Compare Markdown editors for Mac to find the right tool for your workflow

For quick one-off tables, an online generator is fastest. For recurring conversions (CI pipelines, automated docs), Pandoc is the standard choice.

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. MDViewer also renders Mermaid diagrams and JSON files with a collapsible tree view.

If you’re new to .md files, see our guide on how to open Markdown files on Mac. For writing Markdown, compare the best Markdown editors for Mac to find the right tool. Lite is free; Pro adds inline editing, Git history, and PDF export for $9.99 one-time.

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.

Can I create a Markdown table without a header row?
Standard Markdown requires a header row — there is no headerless table syntax. As a workaround, use empty header cells (leave the first row blank) or use an HTML <table> without a <thead> element. See the section above for examples.

How do I add a list inside a Markdown table cell?
Markdown tables don’t support block-level elements like lists. Use <br> tags with bullet characters (•) for a visual list, or switch to an HTML <table> where you can nest real <ul> or <ol> elements inside <td> cells.

How do I create a table in a GitHub README?
Use pipe (|) and hyphen (-) syntax: start with a header row, add a separator row with hyphens, then add data rows. GitHub renders standard GFM tables automatically — no extensions needed. Use colons in the separator row for alignment. See our README template guide for more examples.

What is the basic syntax for Markdown tables?
A Markdown table uses pipes (|) to separate columns and hyphens (-) for the header separator row. The first row is the header, the second row is dashes, and all subsequent rows are data. Leading and trailing pipes are optional but recommended for readability. See the basic syntax section for a copy-paste example.

How do I add a new line inside a Markdown table cell?
Standard Markdown tables don’t support line breaks. Use an HTML <br> tag inside the cell to force a new line: First line<br>Second line. This works on GitHub, GitLab, and most Markdown renderers. See the multi-line cells section for examples.

How do I create a table in GitHub Markdown?
GitHub uses GitHub Flavored Markdown (GFM) tables. Use pipe and hyphen syntax with optional colon alignment. GitHub supports inline formatting and <br> line breaks in cells, but strips colspan/rowspan attributes and most HTML from issues and comments. HTML tables work fully in repository .md files. See the GitHub Markdown tables section for a full compatibility breakdown.

Try MDViewer

MDViewer Lite is free. Pro adds editing, Git history, and PDF export for $9.99. Download and see if it fits your workflow.

Requires macOS 13.0 or later. Intel and Apple Silicon.