Markdown Table Alignment: Left, Center and Right

How do I align columns in a Markdown table?

Alignment lives in the second line of the table, the delimiter row. Each delimiter cell controls the column above and below it.

| Default | Left    | Center  | Right    |
| ------- | :------ | :-----: | -------: |
| text    | text    | text    | 9.99     |
| longer text | longer text | longer text | 1,024.00 |

If you'd rather click than type colons, the Markdown table generator has an alignment toggle on every column and writes the delimiter row for you.

Alignment rules worth knowing

• Only the colons count. :-: and :-----------: both center. GFM needs one hyphen per cell; GitHub Docs suggest three for readability.
• No space between colon and hyphens. Spaces around the cell are fine (| :---: |), but : --- or --- : is not a valid delimiter, and the whole table stops rendering.
• Alignment is per column. The header cell follows the same alignment as the data. There is no per-row or per-cell syntax.
• Colons only work in the delimiter row. A colon in a data cell is plain text.
• The HTML output differs by parser. GitHub's cmark-gfm writes <td align="right">; markdown-it (VS Code, many static sites), Goldmark (Hugo) and Pandoc write style="text-align: right". A site stylesheet that sets text-align on cells overrides the align attribute but not an inline style, which is why the same table can align on one site and not another.

| Item | Qty | Status |
|:-|-:|:-:|
| Apples | 12 | ✅ |
| Pears | 140 | ⏳ |

Worked example: a pricing table

A typical real table mixes all three: text on the left for scanning, short status values centered, and money on the right so the decimal points line up.

| Feature            | Released   | Pro | Monthly cost |
| :----------------- | :--------: | :-: | -----------: |
| Developer API      | 2025-01-15 | ✅  |       $19.00 |
| Enterprise SSO     | 2025-03-01 | ✅  |      $499.00 |
| Dedicated database | 2025-06-30 | ⏳  |    $1,250.50 |

Markdown has no decimal-point alignment. Right alignment lines up decimals only when every number has the same number of decimal places, so write $19.00, not $19, next to $1,250.50. Put the unit in the header (“Monthly cost (USD)”) rather than in each cell when you can; it keeps the column narrow and easier to compare.

What happens without colons?

A --- cell means “no alignment”: the parser writes plain <th> and <td> elements and leaves the rest to CSS. Data cells then inherit the page's text direction, so they show left-aligned in English. Header cells are different: the browsers' default stylesheet centers <th> text, so on a site whose CSS doesn't override it you get centered headers over left-aligned data. If you want the header to sit flush with its column everywhere, say so explicitly with :---.

How do I center only the header?

Pipe syntax can't do this: the colons align the header and the data together. Three workarounds, from most to least portable:

1. HTML inside the header cells (GitHub). Wrap each header in <div align="center"> and keep :--- for the column. GitHub keeps the align attribute.
2. CSS on sites you control. th { text-align: center; } in MkDocs, Docusaurus, Hugo or Jekyll. It won't override an explicit inline style alignment, so leave those columns as ---.
3. A full HTML table with <th align="center"> and plain <td> cells.

| <div align="center">Name</div> | <div align="center">Notes</div> |
| :--- | :--- |
| Ada | Wrote the first program |
| Grace | Built the first compiler |

How do I center the whole table on the page?

Alignment colons move text inside cells; they never move the table. Centering the table itself is a layout job, so the method depends on where the Markdown is rendered.

<div align="center">

| Plan | Price |
| :--- | ----: |
| Free | $0 |
| Pro  | $8 |

</div>

/* Docusaurus: src/css/custom.css · MkDocs: a file listed in extra_css
   Hugo / Jekyll: your theme's stylesheet */
article table {
  width: fit-content;   /* shrink the table to its content (also works for display:block) */
  max-width: 100%;      /* wide tables still scroll instead of overflowing */
  margin-inline: auto;  /* center it */
}

width: fit-content is there because several site themes (and GitHub) style tables as display: block, which makes a plain margin: auto do nothing. If the rule still has no effect, inspect the table: some themes (MkDocs Material, for one) make it inline-block inside a wrapper, and then the wrapper needs text-align: center instead. For a table that spans the full width instead, see column width.

Can I top-align cells vertically?

No. GFM and the other pipe-table flavors have no vertical-alignment syntax. Browsers center cell content vertically by default, which you notice as soon as one cell holds several lines via <br> line breaks and its neighbours float in the middle. The fixes:

<table>
  <tr>
    <th>Step</th>
    <th>Details</th>
  </tr>
  <tr valign="top">
    <td>Install</td>
    <td>Run npm install<br>then npm run build<br>then npm test</td>
  </tr>
</table>

/* Sites where you control the stylesheet */
td, th {
  vertical-align: top;
}

GitHub keeps valign but strips style, so the attribute is the only option there.

Jupyter: tables centered or right-aligned

Jupyter adds its own table CSS on top of the Markdown output, which causes two separate surprises:

• The table is centered on the page. Both the classic Notebook and JupyterLab give tables margin-left: auto; margin-right: auto.
• Cell text is right-aligned. The classic Notebook (and some older JupyterLab releases) right-align all table cells, a style meant for DataFrame output. Explicit colons usually fix it: write :--- for every text column instead of ---.

To move the table itself to the left, override the margin in a custom stylesheet:

/* ~/.jupyter/custom/custom.css
   Classic Notebook loads it automatically; JupyterLab 4.1+ and
   Notebook 7.1+ need custom CSS enabled (LabApp.custom_css = True). */
.jp-RenderedMarkdown table,
.rendered_html table {
  margin-left: 0;   /* stop centering tables on the page */
}

In the classic Notebook, a <style> block with the same rule inside a Markdown cell also works for a trusted notebook. Exact selectors vary between Jupyter versions, so check the rendered HTML with your browser's inspector if a rule doesn't apply.

Alignment support by platform

Common mistakes (broken vs. fixed)

A space between the colon and the hyphens

| Item | Price |
| :--- | --- : |
| Tea  | 3.50  |

| Item | Price |
| :--- | ----: |
| Tea  | 3.50  |

Fewer delimiter cells than header cells

Adding a column to the header and forgetting its delimiter cell is the most common way to break an aligned table: GFM requires the header and delimiter rows to have the same number of cells.

| Item | Qty | Price |
| :--- | --: |
| Tea  | 2   | 3.50  |

| Item | Qty | Price |
| :--- | --: | ----: |
| Tea  | 2   | 3.50  |

Colons in the data instead of the delimiter row

| Item  | Price  |
| ----- | ------ |
| :Tea  | 3.50:  |

| Item | Price |
| :--- | ----: |
| Tea  | 3.50  |

The table validator flags mismatched and malformed delimiter rows with the line number.

When to switch to HTML

Stay with colons for column alignment; it is portable and readable. Switch to an HTML table when you need:

• different alignment for one cell or one row (<td align="…">)
• headers aligned differently from their data, outside GitHub
• vertical alignment (valign) on GitHub, or merged cells (see merged cells)

Remember that GitHub drops style attributes, so use the old align and valign attributes there. For everything else about the pipe syntax, see the Markdown table syntax guide.

Frequently asked questions