How to Make a Table in Markdown (With Examples)

Tables are one of the most useful parts of Markdown and one of the easiest to get wrong. A missing pipe or a misplaced dash and the whole thing collapses into a paragraph of punctuation. This guide covers everything you need to write tables confidently, plus shortcuts for when you already have the data somewhere else.

The basic syntax

A Markdown table has three parts: a header row, a delimiter row, and one or more body rows. Columns are separated by pipes (|).

| Name   | Role      | Location |
| ------ | --------- | -------- |
| Ada    | Engineer  | London   |
| Grace  | Admiral   | Arlington|

That renders as:

Name	Role	Location
Ada	Engineer	London
Grace	Admiral	Arlington

A few rules worth remembering:

• The header row is required. GitHub Flavored Markdown (GFM) has no headerless tables. If you do not want a visible header, you still need the row.
• The delimiter row needs at least three dashes per column in many renderers, so --- is the safe minimum.
• The outer pipes are optional, but including them makes tables easier to read and edit.
• Columns do not need to line up. Padding is purely cosmetic; |a|b| works just as well as a perfectly aligned table.

Aligning columns

Add colons to the delimiter row to control alignment:

| Left | Center | Right |
| :--- | :----: | ----: |
| a    |   b    |     c |

Left	Center	Right
a	b	c

Right alignment is ideal for numbers, so decimal places line up visually.

Formatting inside cells

Cells accept inline Markdown: bold, italic, code, links, and images all work. Block elements do not — you cannot put a list, a heading, or a code block inside a cell.

Two situations trip people up:

1. Pipes in content. A literal | ends the cell. Escape it as \|.
2. Line breaks. A newline ends the row. Where HTML is allowed (GitHub, for example), use <br> to break a line inside a cell.

Building tables without typing pipes

Writing tables by hand is fine for three rows. For anything bigger, let a tool do it:

• Visual editing: the Markdown table generator gives you a spreadsheet-style grid with per-column alignment, row and column reordering, and one-click copy.
• From a spreadsheet or CSV: copy cells from Excel or Google Sheets, or paste a CSV file, into the CSV to Markdown table converter. Quoted fields and commas inside cells are handled correctly.
• From an API response: paste an array of JSON objects into the JSON to Markdown table converter. Every key becomes a column.

All three run entirely in your browser, so private data never leaves your device.

Where tables do not work

Not every platform supports tables. GitHub, GitLab, Reddit, Obsidian, and most documentation tools do. Discord, Slack, WhatsApp, and Telegram do not — they print the pipes literally. For those, put the table inside a code block so the monospace font keeps the columns aligned. The Markdown to Slack converter does this automatically.

Quick reference

You want	Syntax
Left-align	:---
Center	:---:
Right-align	---:
Literal pipe	|
Line break in a cell	<br> (where HTML is allowed)

Want to try it? Open the Markdown editor and paste any example from this post — the preview updates as you type.