Markdown Tables: The Complete Guide

Master Markdown tables — from basic syntax to advanced formatting, alignment, and conversion from spreadsheets and documents.

markdowntablesguideformatting

Tables are the most finicky part of Markdown. Get them right once and you'll save hours of formatting headaches. Here's everything you need to know.

Basic GFM Table Syntax

GitHub-Flavored Markdown (GFM) defines the standard table format:

| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Renders as:

Header 1Header 2Header 3
Cell 1Cell 2Cell 3
Cell 4Cell 5Cell 6

Key rules:

  • Pipes (|) separate columns
  • Dashes in the separator row (---|---|---) define the header boundary
  • Column widths in the source don't matter — the renderer sizes them
  • Trailing pipes are optional but recommended for readability
  • Leading/trailing whitespace in cells is trimmed

Column Alignment

Control text alignment with colons in the separator row:

| Left     | Center   |    Right |
| :------- | :------: | -------: |
| aligned  | centered |  aligned |
  • :--- or --- → left-aligned (default)
  • :---: → center-aligned
  • ---: → right-aligned

Escaping Special Characters

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

| Command      | Description        |
| ------------ | ------------------ |
| `ls \| wc` | Pipe output to wc  |

Vertical bars inside inline code (backticks) don't need escaping.

Inline Formatting Within Cells

Cells support inline Markdown:

| Feature    | Status     | Notes              |
| ---------- | ---------- | ------------------ |
| **Bold**   | ✓ Working  | *Italic* also ok   |
| `Code`   | ✓ Working  | Inline code        |
| [Link](#)  | ✓ Working  | Needs full URL     |

Note: Multi-line content within cells is not supported in standard GFM.

Converting Spreadsheets to Markdown Tables

CSV → Markdown Table

Given data.csv:

Name,Age,City
Alice,30,New York
Bob,25,London

Convert using DocsToMarkdown (drag and drop the .csv file) or manually:

| Name  | Age | City     |
| ----- | --- | -------- |
| Alice | 30  | New York |
| Bob   | 25  | London   |

Excel (.xlsx) → Markdown Table

Each sheet becomes a Markdown table with the sheet name as an H2 heading. DocsToMarkdown handles this automatically when you upload an .xlsx file.

Common Table Mistakes

Missing separator row — Every table needs the |---|---| line after the header:

| Header |
| Cell   |  ← This won't render as a table

Inconsistent column counts — Every row must have the same number of columns:

| A | B |
| - | - |
| 1 | 2 | 3 |  ← Extra column breaks rendering

Blank header cells — Empty headers are valid but confusing. Always provide header text.

Mixing tables with other block elements — Tables can't contain lists, code blocks, or other block-level elements within cells.

Tables in Documentation Platforms

PlatformGFM TablesHTML TablesNotes
GitHub✓✓GFM recommended
GitLab✓✓Same as GitHub
Obsidian✓✗GFM only
Notion✓✗Limited GFM support
Docusaurus✓✓GFM by default
MkDocs✓✓Via extensions
VS Code✓✗Preview supports GFM tables

When to Use HTML Tables Instead

GFM tables are limited. Use HTML tables when you need:

  • Rowspan/colspan (merged cells)
  • Multi-line cell content
  • Nested formatting (lists within cells)
  • Caption elements

Most Markdown renderers support inline HTML:

<table>
  <tr><th>Feature</th><th>GFM</th><th>HTML</th></tr>
  <tr><td>Merged cells</td><td>✗</td><td>✓</td></tr>
  <tr><td>Multi-line</td><td>✗</td><td>✓</td></tr>
</table>

For maximum compatibility, stick with GFM tables whenever possible — they render correctly on every Markdown platform.