Tables in Markdown have an unusual history: John Gruber's original 2004 Markdown specification did not include table syntax at all. Gruber's philosophy was that Markdown should cover the most common formatting needs while deferring to inline HTML for anything more complex — and tables were considered complex. This meant that for years, Markdown authors who needed tables had to write raw HTML table tags within their Markdown documents, creating an awkward mix of simple Markdown syntax and verbose HTML.

The table syntax that most people recognize today — pipes (|) separating columns and hyphens (-) forming the header separator — originated in PHP Markdown Extra, an extension by Michel Fortin published in 2006. This syntax was adopted and refined by GitHub Flavored Markdown (GFM), MultiMarkdown, and other extended Markdown implementations, eventually becoming a de facto standard despite never being part of the original specification. The CommonMark specification, which aims to standardize Markdown, initially omitted tables, but the GFM specification (a CommonMark extension) formally defines the table syntax used on GitHub, GitLab, and many other platforms.

The Markdown table syntax has deliberate limitations that reflect its "lightweight" philosophy. Tables must have a header row — there is no way to create a headerless table in standard Markdown table syntax. Column alignment is specified using colons in the separator row: :--- for left-aligned, :---: for centered, and ---: for right-aligned. Cells cannot span multiple columns (colspan) or multiple rows (rowspan), features that HTML tables support through dedicated attributes. Cell content is limited to inline formatting — you cannot place block elements like paragraphs, lists, or code blocks inside table cells. These constraints keep the syntax simple and line-oriented but mean that complex data presentations still require HTML.

Different Markdown parsers handle table edge cases differently. Some require the leading and trailing pipes on each row, while others make them optional. Some allow rows with different numbers of cells than the header, silently adding empty cells; others reject such rows. Escaped pipes within cell content (\|) are handled inconsistently across implementations. The GFM specification addresses many of these ambiguities but parsers that predate GFM or follow different conventions may produce different results from the same source.

The rendering of Markdown tables also varies between platforms. GitHub and GitLab apply default styling with borders, alternating row colors, and responsive scrolling. Static site generators like Hugo and Jekyll may render bare HTML tables that require custom CSS for visual styling. Documentation platforms like Read the Docs, Notion, and Obsidian each apply their own table styling. This means that a table written in Markdown may look quite different depending on where it is rendered, which is important to consider when writing documentation intended for multiple platforms.

For tables that exceed Markdown's capabilities, authors typically choose between inline HTML tables (preserving the Markdown document format) and external formats like CSV files rendered by platform-specific extensions. Some Markdown processors support extended table syntaxes — MultiMarkdown supports column spanning, and Pandoc supports grid tables with more flexible cell content — but these extensions are not universally supported.