How to organize GitHub Markdown tables

What this covers

Organizing information with tables shows how to build Markdown tables in comments, issues, pull requests, and wikis. You type the table in the GitHub editor (or any .md file), then use Preview. There is no separate table UI and no CLI step on this docs page.

flowchart TD
    Header["Header Row: | Column 1 | Column 2 |"] --> Delimiter["Delimiter Row: | :--- | :---: |"]
    Delimiter --> Alignment["Alignment Syntax: Left, Center, Right"]
    Alignment --> Rows["Data Rows: Content and inline formatting"]
    Rows --> Render["Rendered Responsive HTML Table"]

Create a table

Hyphens define the header separator; pipes separate columns. Include a blank line before the table so GitHub renders it as a table instead of ordinary text.

| First Header  | Second Header || ------------- | ------------- || Content Cell  | Content Cell  || Content Cell  | Content Cell  |

Pipes on either end of each row are optional. Cells can vary in width and do not need to line up visually in the source. Each column in the separator row needs at least three hyphens.

Compact example:

| Command | Description || --- | --- || git status | List all new or modified files || git diff | Show file differences that haven't been staged |

If you edit tables often, enable a monospace font for the Markdown editor under Settings → Appearance (About writing and formatting on GitHub). That makes column pipes easier to scan while you type.

Format content inside cells

Links, inline code, and emphasis work inside cells the same way they do outside tables:

| Command | Description || --- | --- || `git status` | List all *new or modified* files || `git diff` | Show file differences that **haven't been** staged |

Use that for command references, short notes, and status callouts without leaving the table.

Align columns

Put colons on the left, both sides, or right of the hyphen row to left-, center-, or right-align:

| Left-aligned | Center-aligned | Right-aligned || :---         |     :---:      |          ---: || git status   | git status     | git status    || git diff     | git diff       | git diff      |

Right-align is especially useful for numeric rank or count columns (the writing quickstart uses |-----:| for a Rank column).

Escape a pipe character

To show | as cell content rather than a column break, prefix it with a backslash:

| Name     | Character || ---      | ---       || Backtick | `         || Pipe     | \|        |

Common mistakes

Further reading

• GitHub Flavored Markdown Spec
• Basic writing and formatting syntax
• Quickstart for writing on GitHub