Markdown Table Syntax
Markdown tables use pipe | characters to separate columns and hyphens - to create the header divider row:
| Name | Type | Default | |------------|---------|---------| | timeout | number | 3000 | | retries | number | 3 | | verbose | boolean | false |
The column widths don't need to align — Markdown parsers ignore whitespace inside cells. But aligned columns are much easier to read and edit in plain text.
Column Alignment
Colons in the divider row control alignment:
| Left | Center | Right | |:--------|:---------:|---------:| | apples | bananas | cherries | | 100 | 200 | 300 |
:---— left (default):---:— center---:— right
Right-alignment is conventional for numeric columns, making numbers line up visually.
Where Markdown Tables Work
GitHub Flavored Markdown (GFM) renders tables in README files, issues, pull requests, and wikis. Most static site generators (Next.js with MDX, Docusaurus, Hugo, Jekyll) support tables. Notion, Obsidian, and most modern writing tools that support Markdown also render tables.
Standard CommonMark does not include tables — they are a GFM extension. If your environment uses strict CommonMark, check whether table support is enabled via a plugin.
Special Characters in Cells
To include a literal pipe | in a cell, escape it with a backslash: \|. Line breaks inside cells are not supported in standard Markdown tables — cells are always single-line. For multi-line cell content, consider a definition list or a code block instead.
Building Tables from Spreadsheet Data
Creating a Markdown table by hand for more than a few rows is tedious and error-prone. A common workflow is to maintain the data in a spreadsheet (Excel, Google Sheets), export to CSV, then convert to Markdown. A Markdown table generator that accepts CSV input automates this conversion. The DevHexLab Markdown Table Generator lets you edit cells in a visual grid, set column alignment per column, and paste or import CSV — then copies the finished Markdown table to the clipboard.
Keeping Tables Maintainable
Long tables in Markdown files become hard to maintain as content grows. Consider whether the data belongs in a table or in a different format — a definition list for key-value pairs, a code block for structured data, or an external data source with generated documentation. For API reference docs with many parameters, a code-generated table (from type definitions or JSON schema) is more maintainable than a hand-maintained Markdown file.
Rendering Differences
Markdown table rendering is broadly consistent across tools, but column widths, font, and alignment rendering vary. Always preview your table in the actual environment (GitHub, your docs site) rather than assuming a local preview is identical. GitHub in particular has its own CSS for table styling that affects spacing and borders.