Home/Docs/Markdown Tables

Markdown Tables

Markdown tables make it easy to organize information into rows and columns using simple plain text syntax. They are widely used in GitHub README files, project documentation, technical blogs, Obsidian notes, and many other Markdown editors.

Instead of writing HTML `<table>` elements, you can create readable tables with pipes (`|`) and hyphens (`-`). This keeps your documents clean, portable, and easy to edit.

This guide explains everything you need to know about Markdown tables — from basic syntax and alignment to platform compatibility, common mistakes, and best practices.

Build tables faster: Use the Markdown Table Generator to create tables visually, then preview them in the Markdown Editor.

Open EditorDownload PDF

What are Markdown Tables?

A Markdown table is a simple way to display structured information using rows and columns.

Unlike spreadsheets, Markdown tables are written entirely with plain text, making them easy to edit in any text editor.

Example

| Name | Language |
|------|----------|
| React | JavaScript |
| Django | Python |
| Laravel | PHP |

Output

Rendered Output

Name Language
React JavaScript
Django Python
Laravel PHP

Markdown tables are supported by many modern Markdown implementations, including GitHub, GitLab, Obsidian, VS Code, and most documentation generators.

Why Use Markdown Tables?

Markdown tables provide several advantages over writing HTML tables manually.

Easy to read — Even before rendering, the data stays organized in rows and columns.

Faster to write — Creating a table only requires pipes (|) and hyphens (-).

GitHub compatible — GitHub Flavored Markdown (GFM) fully supports tables in README files and docs.

Plain text format — Files remain lightweight, portable, and version-control friendly.

Great for documentation — Common uses include feature comparisons, API parameters, configuration options, pricing plans, command references, and compatibility charts.

Basic Markdown Table Syntax

The basic syntax consists of a header row, a separator row, and one or more data rows.

| Name | Age | Country |
|------|-----|----------|
| John | 28 | USA |
| Emma | 25 | Canada |
| Liam | 31 | Australia |

Output

Rendered Output

Name Age Country
John 28 USA
Emma 25 Canada
Liam 31 Australia

The separator row (---) tells the Markdown parser that the first row contains column headings. You can create as many columns and rows as needed.

Understanding the Table Structure

Every Markdown table has three important parts.

Header row

The first row contains column names.

| Product | Price | Stock |

Separator row

The second row separates headers from data. Use at least three hyphens per column.

|---------|-------|-------|

Data rows

Every following row contains your actual data.

| Laptop | $999 | In Stock |
| Mouse | $25 | Available |
| Keyboard | $70 | Limited |

When Should You Use Markdown Tables?

Markdown tables work best when displaying structured information such as:

  • Product comparisons
  • Feature lists and configuration settings
  • API documentation and parameter lists
  • Pricing plans and software compatibility
  • Commands, keyboard shortcuts, and file formats
  • Tool comparisons and release notes

If your content is naturally organized into rows and columns, a Markdown table is usually the best choice.

Markdown Table Examples

Simple table

| Name | Age |
|------|-----|
| Alex | 24 |
| Emma | 29 |

Product comparison

| Product | Price | Rating |
|---------|-------|--------|
| Laptop | $999 | ⭐⭐⭐⭐⭐ |
| Mouse | $25 | ⭐⭐⭐⭐ |
| Keyboard | $79 | ⭐⭐⭐⭐⭐ |

API parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| id | Yes | User ID |
| limit | No | Number of results |
| sort | No | Sort order |

Pricing table

| Plan | Users | Price |
|------|-------|-------|
| Free | 1 | $0 |
| Pro | 10 | $19 |
| Business | Unlimited | $49 |

Markdown Table Alignment

By default, Markdown aligns all columns to the left. Change alignment using colons (:) in the separator row.

Left alignment

| Name | Price |
|:-----|:------|
| Mouse | $25 |

Center alignment

| Name | Price |
|:----:|:-----:|
| Mouse | $25 |

Right alignment

| Name | Price |
|-----:|------:|
| Mouse | $25 |

Mixed alignment (common for docs)

| Product | Quantity | Price |
|:---------|:--------:|------:|
| Laptop | 3 | $999 |
| Mouse | 25 | $19 |
| Keyboard | 12 | $89 |

Text → left, numbers → right, status badges → center.

Formatting and Structure Tips

Neat spacing

Good:

| Name | Country | Age |
|------|---------|-----|
| Alex | USA | 25 |

Still valid but harder to read:

|Name|Country|Age|
|---|---|---|
|Alex|USA|25|

Empty cells

Leave a cell blank when data is missing.

| Name | Email |
|------|-------|
| Alex | alex@example.com |
| Emma | |
| John | john@example.com |

Consistent column count

Every row must match the header. This is incorrect:

| Name | Age |
|------|-----|
| Alex |

Tables without visible headers

Standard Markdown requires a header row. If you don't want meaningful labels, use generic names:

| Column 1 | Column 2 |
|----------|----------|
| Apple | Fruit |
| Carrot | Vegetable |

Markdown Tables by Platform

Platform Table Support
GitHub ✅ Full (GFM)
GitLab ✅ Full
VS Code Preview ✅ Full
Obsidian ✅ Full
Notion Partial
Discord ❌ Plain text only

GitHub

Tables render in README files, Wikis, Issues, Pull Requests, and Discussions — no extra syntax required.

VS Code

Press Ctrl+Shift+V (or Cmd+Shift+V on Mac) to preview. Table formatter extensions help keep columns aligned.

Obsidian

GFM tables work natively. Community plugins like Advanced Tables simplify editing.

Discord

Discord does not support Markdown tables — use code blocks, images, or share a file instead.

Notion

Markdown import may not preserve table formatting exactly. Review tables after import or convert to HTML first.

Content Inside Markdown Tables

Links

| Tool | Link |
|------|------|
| Editor | [Markdown Editor](/tools/markdown-editor) |
| Generator | [Table Generator](/tools/markdown-table-generator) |

See the Markdown Links guide for full link syntax.

Images

| Logo | Product |
|------|---------|
| ![Logo](logo.png) | MDConvertHub |

See Markdown Images for alt text and path tips.

Inline code

| Command | Description |
|---------|-------------|
| `npm install` | Install dependencies |
| `npm run dev` | Start dev server |

Emojis

| Feature | Status |
|---------|--------|
| Tables | ✅ |
| Videos | ❌ |

Lists and complex HTML

Simple text in cells works everywhere. Bullet lists inside cells usually require HTML and have limited GitHub support.

Markdown Table Limitations

Standard Markdown and GFM do not support:

  • Merged rows or columns (rowspan / colspan)
  • Custom column widths
  • Background colors, borders, or cell padding
  • Table captions (use a heading above the table instead)
  • Nested tables
  • Fenced code blocks inside cells (use inline `code` or place blocks below the table)

Merged cells example (use HTML instead)

<table>
<tr>
<th>Name</th>
<th colspan="2">Details</th>
</tr>
<tr>
<td>John</td>
<td>Developer</td>
<td>Remote</td>
</tr>
</table>

Column width (HTML when required)

<table>
<tr>
<th width="200">Name</th>
<th>Description</th>
</tr>
</table>

Support for inline HTML depends on your Markdown renderer.

Markdown Tables vs HTML Tables

Markdown Tables HTML Tables
Easy to write More flexible
Supported almost everywhere Depends on renderer
Great for documentation Better for advanced layouts
Mobile-friendly Can become complex
Best for README files Best for custom designs

For most documentation, Markdown tables are the better choice. Use HTML only when you need merged cells, fixed widths, colors, or custom layouts.

Best Practices

  • Keep header names short and descriptive.
  • Use consistent spacing for readability.
  • Align numbers to the right (---:).
  • Use tables only for structured data — not page layout.
  • Keep every row the same column count as the header.
  • Avoid very wide tables on mobile — split into smaller tables if needed.
  • Preview before publishing on GitHub, VS Code, or your docs platform.
  • Use the Markdown Table Formatter to clean up alignment in existing tables.

Common Mistakes

Missing separator row

Incorrect

| Name | Age |
| Alex | 24 |

Correct

| Name | Age |
|------|-----|
| Alex | 24 |

Uneven columns

Every row must have the same number of pipe-separated cells as the header.

Forgetting pipe characters

Incorrect: Name Age Country

Correct: | Name | Age | Country |

Using tables for layout

Markdown tables organize data — don't use them to position buttons, images, or page sections.

Large paragraphs in cells

Keep cells concise. Move long explanations below the table or link to another section.

Real-World Examples

Feature comparison

| Feature | Free | Pro |
|---------|:----:|:---:|
| Live Preview | ✅ | ✅ |
| Export PDF | ❌ | ✅ |

Software compatibility

| Platform | Supported |
|----------|:---------:|
| GitHub | ✅ |
| VS Code | ✅ |
| Discord | Partial |

Keyboard shortcuts

| Shortcut | Action |
|----------|--------|
| Ctrl + C | Copy |
| Ctrl + V | Paste |
| Ctrl + Z | Undo |

Tables are especially common in GitHub README files for features, requirements, browser support, and changelog summaries.

Save Time with a Markdown Table Generator

Writing large tables manually means counting pipes and separator lines. The Markdown Table Generator lets you:

  • Build tables visually
  • Add or remove rows and columns instantly
  • Align text without manual colons
  • Copy clean Markdown with one click

You can also convert existing data with CSV to Markdown Table, JSON to Markdown Table, or Excel to Markdown Table, then preview in the Markdown Editor.

Continue Learning

Continue learning Markdown with these guides:

Available now

Coming soon to MDConvertHub Docs

  • Markdown Code Blocks

The fastest way to learn is to build a table in the Markdown Table Generator, paste it into the Markdown Editor, and preview the result before adding it to your README or docs.

Frequently Asked Questions

  1. 1

    How do I create a table in Markdown?

    Use pipes (|) to separate columns and hyphens (-) in a separator row below the header. Example: | Name | Age | followed by |------|-----| and data rows.

  2. 2

    Are Markdown tables supported on GitHub?

    Yes. GitHub Flavored Markdown fully supports tables in README files, Wikis, Issues, Pull Requests, and Discussions.

  3. 3

    Can I align text inside Markdown tables?

    Yes. Use colons in the separator row: :--- for left, :---: for center, ---: for right.

  4. 4

    Can Markdown merge table cells?

    No. Standard Markdown does not support rowspan or colspan. Use HTML tables when you need merged cells.

  5. 5

    Can I resize table columns?

    No. Markdown determines column widths automatically. Use HTML with width attributes if your renderer supports it.

  6. 6

    Can I put images or links inside Markdown tables?

    Yes. Normal Markdown link and image syntax works inside table cells on GitHub and most editors.

  7. 7

    Why is my Markdown table not rendering correctly?

    Common causes: missing separator row, uneven column counts, missing pipe characters, incorrect alignment syntax, or an unsupported renderer.

  8. 8

    Which Markdown editors support tables?

    GitHub, GitLab, VS Code, Obsidian, Typora, MarkText, and Joplin support tables well. Notion and Discord have limited or no support.

  9. 9

    Is there an easier way to create Markdown tables?

    Yes. Use the Markdown Table Generator on MDConvertHub to build tables visually and copy the generated Markdown.