Tables are one of the more powerful features in Markdown — and one of the most commonly searched. Whether you’re documenting an API, comparing options, or presenting data, a Markdown table turns rows and columns into clean, readable structure. Here’s everything you need to know.
Basic Table Syntax
A Markdown table uses pipe characters (|) to separate columns and a row of hyphens (---) to separate the header from the body:
| Name | Role | Location |
| ---------- | ---------- | ----------- |
| Alice | Engineer | Berlin |
| Bob | Designer | Tokyo |
| Carol | Product | New York |Output:
| Name | Role | Location |
|---|---|---|
| Alice | Engineer | Berlin |
| Bob | Designer | Tokyo |
| Carol | Product | New York |
Three things are required: a header row, a separator row with at least three hyphens per column, and one or more data rows. The pipes at the edges are optional in most parsers but recommended for readability.
Column Alignment
Control text alignment by adding colons to the separator row:
| Left | Center | Right |
| :----------- | :----------: | -----------: |
| Left-aligned | Centered | Right-aligned|
| text here | text here | text here || Left | Center | Right |
|---|---|---|
| Left-aligned | Centered | Right-aligned |
| text here | text here | text here |
:---— left alignment (default):---:— center alignment---:— right alignment
Right-alignment is especially useful for numeric columns.
Inline Formatting Inside Tables
You can use inline Markdown formatting inside table cells:
| Feature | Status | Notes |
| ------------- | ------------- | ------------------------- |
| **Bold text** | ✅ Supported | Use `**` syntax |
| *Italic text* | ✅ Supported | Use `*` or `_` |
| `Inline code` | ✅ Supported | Use backticks |
| [Links](/) | ✅ Supported | Full URL or relative path |
| Line breaks | ❌ Not easy | Use `<br>` as workaround |You cannot use block-level elements (headings, paragraphs, lists) inside table cells. For complex cell content, consider using a different document structure.
Line Breaks Inside Cells
Standard Markdown doesn’t support newlines inside cells. The workaround is the HTML <br> tag, which most parsers respect:
| Name | Address |
| ----- | ------------------------------------- |
| Alice | 123 Main Street<br>Berlin, Germany |This is fine for occasional use, but if you find yourself using <br> everywhere, a table might not be the right structure for your content.
Tables Don’t Need Perfect Alignment
The pipes don’t need to line up for the table to render correctly. This:
| Name | Role | Location |
|---|---|---|
| Alice | Engineer | Berlin |
| Bob | Designer | Tokyo |Renders identically to the neatly-spaced version. Many editors (VS Code, Typora) have table formatting shortcuts that auto-align columns for you — use them if readability matters.
Escaping Pipe Characters
If your cell content contains a literal pipe character, escape it with a backslash:
| Keyboard Shortcut | Action |
| ----------------- | ------------------- |
| `Ctrl \| Cmd + S` | Save file |
| `Ctrl \| Cmd + Z` | Undo last action |Converting Tables to Other Formats
Markdown tables are well-supported in most export formats, but the visual result varies:
| Export Format | Table Rendering |
|---|---|
| Formatted table with borders (browser-dependent) | |
| DOCX (Word) | Native Word table, fully editable |
| HTML | <table> element with browser default styles |
| Plain text | Loses structure — cells become space-separated |
For styled table export to PDF or DOCX, use Markdown Monk’s converter — it handles column widths and header rows cleanly across all supported formats.
Common Mistakes
Forgetting the separator row — The | --- | line between header and body is mandatory. Without it, the entire block renders as plain text.
Empty cells — Leave two spaces or nothing between pipes: | | | works fine.
Too many columns — There’s no column limit, but very wide tables are hard to read on narrow screens. Consider splitting complex data or using a different structure.
Quick Reference
| Header 1 | Header 2 | Header 3 |
| :------- | :------: | -------: |
| Left | Center | Right |
| data | data | data |