How to Create Tables in Markdown

Everything you need to know about Markdown tables — syntax, alignment, generators, and common pitfalls.

5 min read

Tables are one of the more awkward parts of Markdown. The syntax is simple in theory but gets fiddly fast, especially with wider data. This guide covers everything from basic syntax to alignment tricks, common mistakes, and tools that make the whole process less painful.

Basic Table Syntax

A Markdown table has three parts: the header row, the separator row, and the data rows. Columns are separated by pipes (|), and the separator row uses dashes to divide the header from the body.

| Name    | Language   | Stars |
| ------- | ---------- | ----- |
| React   | JavaScript | 210k  |
| Vue     | JavaScript | 205k  |
| Svelte  | JavaScript | 73k   |

The leading and trailing pipes are optional in most parsers, but I recommend including them. It makes the source easier to read and avoids subtle parsing issues with some tools.

The number of dashes in the separator row doesn't matter — one dash per column is technically enough. But lining things up makes your source Markdown much easier to scan:

| Name | Language | Stars |
| - | - | - |
| React | JavaScript | 210k |

That works, but it looks messy. Take the extra seconds to pad things out.

Column Alignment

By default, table content is left-aligned. You can control alignment per column using colons in the separator row:

| Left      | Center     | Right    |
| :-------- | :--------: | -------: |
| aligned   | aligned    | aligned  |
| left      | center     | right    |
  • :--- or :---- — left-aligned (the default)
  • :---: or :----: — center-aligned
  • ---: or ----: — right-aligned

Right alignment is handy for numeric columns like prices, counts, or percentages. Center alignment works well for short status labels or boolean values.

Common Mistakes

Tables trip people up more than most Markdown features. Here are the issues I see most often:

Forgetting the Separator Row

Without the separator row (the one with dashes), most parsers won't recognize your table at all. It'll just render as plain text with pipes in it.

| This | Won't | Work |
| As   | A     | Table |

You need that dash row between the header and the data:

| This | Will  | Work  |
| ---- | ----- | ----- |
| As   | A     | Table |

Uneven Column Counts

Every row should have the same number of pipe-separated columns. If one row has three columns and another has four, the rendering gets unpredictable. Some parsers handle it gracefully, others break.

Pipes in Cell Content

If your cell content includes a literal pipe character, escape it with a backslash:\|. Otherwise the parser thinks you're starting a new column.

No Blank Line Before the Table

Some Markdown parsers need a blank line before the table starts. If your table isn't rendering, try adding an empty line above it.

Using a Table Generator

Typing out table syntax by hand is fine for small tables. But once you get past four or five columns, or more than a handful of rows, it gets tedious. You spend more time counting dashes and aligning pipes than writing actual content.

That's where a table generator helps. MDConvert's Table Generator lets you build tables visually — add rows and columns, type your data, set alignment, and copy the formatted Markdown output. It's faster and you don't have to worry about alignment bugs.

Converting Data to Tables

A common workflow: you have data in a spreadsheet or a CSV export, and you need it in Markdown format. Doing this by hand is not realistic for anything more than a few rows.

The quickest approach is to export your data as CSV, then run it through a converter. MDConvert's CSV to Markdown tool handles this — paste your CSV, get formatted Markdown back. It preserves headers and handles quoted fields with commas inside them.

If your data is in JSON format (say, from an API response), the JSON to Markdown converter can turn arrays of objects into clean tables where each key becomes a column header.

The general process looks like this:

  1. Export your data to CSV or JSON
  2. Paste it into the converter
  3. Check the preview and adjust column alignment if needed
  4. Copy the output into your Markdown document

Tips for Large Tables

Large tables in Markdown get unwieldy. Here are some ways to keep them manageable:

  • Don't force alignment in source. If the table has wide columns, trying to pad everything so the pipes line up will make your file massive. It's okay if the source looks ragged — the rendered output will still be fine.
  • Split into multiple tables. If you have 15 columns, consider whether the data actually needs to be in one table. Two smaller tables are often easier to read than one wide one.
  • Consider HTML for complex layouts. Markdown tables don't support merged cells, rowspans, or colspans. If you need those, drop down to an HTML <table> — most Markdown parsers will render inline HTML.
  • Use a tool. Once a table goes beyond about 5x5, editing it by hand is fighting the format. Use a visual editor or a converter.

Markdown Table Limitations

It's worth knowing what Markdown tables can't do so you don't waste time trying:

  • No cell merging (colspan or rowspan)
  • No multi-line content within a single cell (some parsers allow <br> tags)
  • No cell background colors or borders
  • No nested tables
  • Limited inline formatting — bold and italic work, but complex elements don't

For anything beyond what pipe tables support, HTML is your fallback. And since most Markdown renderers pass HTML through unchanged, you can mix both in the same document without issues.