Markdown Table Generator

About Markdown Table Generator

Markdown Table Syntax

A markdown table is three things: a header row, a separator row of dashes with optional colons for alignment, and one or more body rows, all delimited by pipe (|) characters. The GFM specification requires the separator row to contain at least one dash per column and allows a leading or trailing pipe on each line.

Alignment	Separator Syntax	Example
Left (default)	:---	| Left |
Centre	:---:	| Centre |
Right	---:	| Right |

A basic two-column table looks like this: the header row has pipe-separated values, followed by a separator row (| --- | --- |), followed by data rows. The visual editor handles all this formatting automatically.

Where Markdown Tables Work

Platform	Table Support	Notes
GitHub (README, issues, PRs, wikis)	Full	The most common use case for markdown tables
GitLab	Full	Same syntax as GitHub
Notion	Full	Also converts pasted markdown tables to native tables
Obsidian	Full	Renders in preview mode, raw syntax in edit mode
VS Code preview	Full	Built into the markdown preview panel
Slack	No	Slack does not render markdown tables - use code blocks instead
Discord	No	Same as Slack - wrap in triple backticks for monospace alignment
Reddit	Full	Supported in new Reddit and most apps
Jekyll / Hugo / Astro	Full	Static site generators render markdown tables as HTML

Import from CSV or Spreadsheets

Click Import CSV and paste comma-separated or tab-separated data. The first row becomes headers and the rest become body rows. This handles the most common workflow: you have data in Excel, Google Sheets, or a database export and need to include it in documentation.

Source	How to Get Tab-Separated Data
Google Sheets	Select cells, Ctrl/Cmd+C - clipboard contains TSV
Excel	Select cells, Ctrl/Cmd+C - clipboard contains TSV
CSV file	Open in text editor, copy the contents
Database query	Export as CSV or copy from results grid

For viewing and exploring CSV files before converting them, the CSV Viewer renders them as sortable, filterable tables.

Formatting Best Practices

Practice	Why
Align pipes vertically in source	Makes the raw markdown readable in diffs and code reviews - this tool does it automatically
Keep tables under 5-6 columns	Wide tables overflow on mobile and become hard to scan
Use right-align for numbers	Decimal points line up, making columns scannable
Keep header text short	Long headers create very wide columns
Escape pipes in cell content	Use \| if your cell content contains a literal pipe character
No merged cells	Markdown tables do not support colspan or rowspan - use HTML if needed

Markdown Tables vs HTML Tables

Feature	Markdown Table	HTML Table
Syntax complexity	Simple - pipes and dashes	Verbose - requires thead, tbody, tr, th, td tags
Merged cells	Not supported	colspan and rowspan
Nested content	Limited - inline formatting only	Any HTML element
Styling	Platform default only	Full CSS control
Readability in source	Excellent - readable as plain text	Poor - hard to read raw markup
GitHub rendering	Clean, consistent	Rendered but some CSS restrictions

Use markdown tables when the data is simple (text, numbers, short strings) and will be read on platforms that support markdown. Switch to HTML when you need merged cells, complex formatting, or nested elements.

Special Characters in Cells

Character	Problem	Solution
| (pipe)	Interpreted as column separator	Escape as \|
Newline	Breaks the table row	Use <br> for line breaks within cells
Leading/trailing spaces	Trimmed by most renderers	Use &nbsp; if whitespace is meaningful
Backticks	May conflict with inline code	Use HTML <code> tags instead

Worked Example: Converting a Spreadsheet to Markdown

Say you have this data in Google Sheets and want to drop it into a GitHub README:

Name	Role	Commits
Alice	Lead	412
Bob	Backend	287
Chloe	Frontend	195

Select the three rows in Sheets, press Ctrl/Cmd+C, click Import CSV here, and paste. The clipboard arrives as TSV (tab-separated), which the parser detects automatically. Set the Commits column to right-align so the numbers line up. The output will read:

| Name  | Role     | Commits |
| :---- | :------- | ------: |
| Alice | Lead     |     412 |
| Bob   | Backend  |     287 |
| Chloe | Frontend |     195 |

Paste that into any .md file in a GitHub repo and it renders as a styled HTML table on github.com. The same markdown also renders in GitLab, Bitbucket, Gitea, Codeberg, and the built-in VS Code markdown preview.

How Popular Is Markdown for Documentation?

Markdown is now the default writing format for developer documentation. The Stack Overflow 2024 Developer Survey found that roughly 70% of professional developers work with Markdown at least occasionally, second only to HTML and CSS among markup languages. GitHub hosts well over 420 million public repositories as of 2025, with a README.md file expected in almost every one - that is the single largest use case for markdown tables in the world.

Use Case	Typical Table Need	Notes
Open-source README	Feature matrix, supported platforms, CLI options	GitHub renders GFM tables by default
API documentation	Endpoints, parameters, response fields	Often generated but sometimes hand-written
Changelog / release notes	Breaking changes, migration steps	Keep headers short so mobile users can scan
Pull request descriptions	Before/after benchmarks, checklist status	GitHub PR body supports full GFM
Technical blog (Jekyll, Hugo, Astro)	Comparison tables, benchmark data	Tables are rendered by the site generator
Internal wikis (Notion, Obsidian)	Decision records, team rosters	Notion converts pasted markdown to native tables automatically

GFM vs CommonMark: Why Tables Are Extension Syntax

Tables are not part of the original CommonMark specification. CommonMark, the spec that defines core Markdown, intentionally left tables out because early Markdown from John Gruber did not define them. GitHub Flavored Markdown added tables as an extension in 2014, and most renderers now support them: python-markdown with the tables extension, markdown-it with the markdown-it-table plugin, remark-gfm, pandoc with pipe_tables, and MultiMarkdown.

The practical consequence is that a pipe-delimited table might render on GitHub but not in a minimal CommonMark-only renderer. Almost every modern tool ships with GFM support or a table plugin enabled, so this rarely bites in practice, but it is worth knowing when you write for less common platforms. If you need true portability, the HTML Prettifier can format an equivalent HTML table that works everywhere.

Why Alignment Colons Matter

The colon placement in the separator row is the only way to control alignment in a GFM table. Left is the default, centre uses colons on both sides of the dashes, and right uses a colon only at the end. Without colons, numbers in the body render left-aligned, which makes columns of financial data, benchmarks, or counts much harder to read.

Column Type	Recommended Alignment	Reason
Labels, names, categories	Left	Left-aligned text is easier to scan top-to-bottom
Numbers, counts, percentages	Right	Decimal points and digit places line up vertically
Status badges, short codes	Centre	Centre-aligned tokens look balanced in a narrow column
Mixed content (e.g. "N/A" and "12")	Right	Keeps numeric cells aligned; text cells still read fine

Keyboard Workflow Tips

The fastest way to fill a table is to start with Import CSV. Copy a block of cells from any spreadsheet application, paste, and the headers and rows populate in one step. From there, Tab moves between cells left-to-right, Shift+Tab moves back, and the alignment button above each column cycles through left, centre, and right. When you are done, the Copy Markdown button writes the full output to your clipboard - no need to select the text manually. If a table grows past five or six columns, consider splitting it into two smaller tables on mobile; GitHub wraps wide tables in a horizontal scroll container, but most readers will miss the overflow and only see the first few columns.

Common Mistakes

Mistake	What Happens	Fix
Missing separator row	The table renders as one row of pipe-separated plain text	The separator row is mandatory, even for single-row tables
Fewer separator cells than header cells	Some parsers render only the matching columns, others ignore the table entirely	Match the separator cell count exactly
Unescaped pipe in a cell	A literal | inside data splits the cell into two columns	Escape as \| or replace with the HTML entity |
Multi-line cell content	A newline inside a cell breaks the row	Use <br> for soft line breaks within a cell
Trying to merge cells	Markdown tables do not support colspan or rowspan	Fall back to an HTML table when merged cells are essential
Tables wider than ~6 columns	Mobile renderers either add horizontal scroll or truncate	Split into two narrower tables or use a description list

To preview how your generated table renders, paste it into the Markdown Preview tool. For converting between JSON and CSV data formats, the JSON to CSV Converter handles structured data. All processing runs locally in your browser.

Sources

• GitHub Flavored Markdown Spec - Tables
• CommonMark Specification
• GitHub Docs - Organizing Information with Tables
• GitLab Flavored Markdown - Tables
• Stack Overflow 2024 Developer Survey - Technology
• Pandoc Manual - Pipe Tables Extension