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.
Prefer a visual tool? The free Markdown Table Generator builds the syntax for you — fill in a grid, set column alignment, import a CSV, and copy the finished table. This guide explains what it’s producing.
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.
Tables Without a Header Row
Standard Markdown tables always require the separator row, which means a header row is technically mandatory. To create a table without a visible header, leave the header cells empty:
| | |
| ----- | ------ |
| Alice | Berlin |
| Bob | Tokyo |The separator line is still needed — it’s what tells the parser this is a table at all. Some renderers show a thin empty header band; others collapse it to nothing. In the Markdown Table Generator, switch the Header row toggle off and it writes this empty-header table for you automatically.
Setting Column Width
Markdown itself has no syntax for column widths — parsers size each column to fit its content. If you need explicit widths, the only reliable option is to drop to an HTML <table>, which most Markdown renderers (including GitHub and static-site generators) pass straight through:
<table>
<colgroup>
<col style="width:30%">
<col style="width:70%">
</colgroup>
<tr><th>Field</th><th>Description</th></tr>
<tr><td>Name</td><td>The user's full name</td></tr>
</table>For most documents, letting the renderer auto-size columns is the better choice — fixed widths often break on narrow screens.
Spanning Cells and Nested Tables
Two things Markdown tables genuinely cannot do:
- Merged cells (
colspan/rowspan) — there’s no pipe syntax for spanning a cell across columns or rows. - Nested tables — you can’t place one table inside another table’s cell.
These are limitations of the Markdown table format, not a syntax you’ve overlooked. When you truly need a merged or nested cell, use raw HTML <table> markup inside your Markdown file — GitHub, GitLab, and most static-site generators render it. If the data is that complex, though, it’s often a sign the content wants a different structure entirely.
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.
Skip the syntax — use the generator
Once you understand how tables work, you rarely want to align pipes by hand. Our free Markdown Table Generator lets you fill in a visual grid, set column alignment with a click, import CSV or an existing table, and copy the finished Markdown — or export it straight to DOCX.
Quick Reference
| Header 1 | Header 2 | Header 3 |
| :------- | :------: | -------: |
| Left | Center | Right |
| data | data | data |