Markdown Tables: How to Create, Align, and Style Them

Markdown tables use pipes (|) and dashes (-) to define columns and rows. They’re part of the GitHub Flavored Markdown (GFM) spec, not the original markdown standard. Every major markdown renderer supports them, including GitHub, GitLab, VS Code, Obsidian, and MDtoLink.

Basic Table Syntax

A table needs at minimum a header row, a separator row, and one data row.

| Name    | Language   | Stars |
|---------|------------|-------|
| React   | JavaScript | 220k  |
| Vue     | JavaScript | 207k  |
| Svelte  | JavaScript | 78k   |

The separator row (the one with dashes) tells the parser “this is a table.” Without it, you just have lines of text with pipes.

Spacing inside cells doesn’t matter. The parser ignores extra whitespace. These two tables render identically:

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

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

The aligned version is easier to read in source, but both produce the same output. Outer pipes are optional too: Name | Language | Stars works, though most people include them for clarity.

Column Alignment

Add colons to the separator row to control text alignment within columns.

| Left-aligned | Centered    | Right-aligned |
|:-------------|:-----------:|--------------:|
| text         | text        | text          |
| more text    | more text   | more text     |

The rules are simple:

Left alignment is the default, so :--- and --- behave the same way. Right alignment is useful for numbers. Center alignment works well for short labels or status indicators.

Formatting Inside Cells

You can use most inline markdown inside table cells.

| Feature     | Syntax              | Notes                        |
|-------------|---------------------|------------------------------|
| **Bold**    | `**text**`          | Works in all cells           |
| *Italic*    | `*text*`            | Works in all cells           |
| `Code`      | `` `code` ``        | Good for variable names      |
| [Links](/)  | `[text](url)`       | Full URL or relative path    |
| Images      | `![alt](url)`       | Renders inline, can be large |

Inline code is especially useful in technical documentation. If you’re listing API parameters, putting the parameter name in backticks makes it stand out:

| Parameter   | Type     | Required | Description            |
|-------------|----------|----------|------------------------|
| `id`        | `string` | Yes      | The document ID        |
| `format`    | `string` | No       | Output format (md/html)|
| `published` | `boolean`| No       | Filter by publish state|

What You Can’t Do

Markdown tables have real constraints. Knowing the limits up front saves you from fighting the syntax.

No merged cells. There’s no colspan or rowspan. Every row has the same number of columns. If you need merged cells, drop down to HTML.

No multi-line content in a single cell. A table row must be a single line. You can’t put a paragraph break or a list inside a cell using standard markdown. Some extended parsers support <br> tags for line breaks within cells:

| Step | Description                            |
|------|----------------------------------------|
| 1    | Clone the repo<br>Run `pnpm install`   |
| 2    | Create `.env` from `.env.example`      |

No nested tables. You can’t put a table inside a table cell.

No column width control. The renderer decides column widths. Source formatting (extra spaces) has no effect on the rendered output.

Workarounds for Common Problems

Long cell content wrapping badly

If a cell has a long string (like a URL), the table can get too wide. Options:

1. Use a link with short text instead of a bare URL
2. Abbreviate the content and add a footnote
3. Switch to an HTML table with style="word-break: break-all"

Pipe characters inside cells

If your cell content contains a literal |, escape it with a backslash:

| Command       | Description              |
|---------------|--------------------------|
| `a \| b`      | Logical OR in some shells|

Cells with backticks

To put inline code that contains backticks inside a table cell, use double backticks:

| Example                   | Output        |
|---------------------------|---------------|
| ``` ``code with `ticks` `` ``` | `code with `ticks`` |

When tables aren’t enough

For complex layouts (merged cells, nested content, variable column widths), use HTML directly:

<table>
  <thead>
    <tr>
      <th colspan="2">Server Configuration</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>Host</strong></td>
      <td>0.0.0.0</td>
    </tr>
    <tr>
      <td><strong>Port</strong></td>
      <td>3000</td>
    </tr>
  </tbody>
</table>

Most markdown renderers will render inline HTML tables correctly. GitHub, GitLab, and MDtoLink all support this.

Copy-Paste Templates

Here are some ready-to-use table templates. Copy the raw markdown and fill in your data.

Feature comparison

| Feature          | Free | Pro  | Enterprise |
|------------------|:----:|:----:|:----------:|
| API access       | Yes  | Yes  | Yes        |
| Custom domains   | No   | Yes  | Yes        |
| Analytics        | No   | Yes  | Yes        |
| SSO              | No   | No   | Yes        |
| Priority support | No   | No   | Yes        |

API endpoint reference

| Method | Endpoint         | Description              |
|--------|------------------|--------------------------|
| GET    | `/api/docs`      | List all documents       |
| GET    | `/api/docs/:id`  | Get a single document    |
| POST   | `/api/docs`      | Create a new document    |
| PUT    | `/api/docs/:id`  | Update a document        |
| DELETE | `/api/docs/:id`  | Delete a document        |

Changelog

| Version | Date       | Changes                    |
|---------|------------|----------------------------|
| 2.1.0   | 2026-01-20 | Added table export support |
| 2.0.0   | 2026-01-10 | Breaking: new API format   |
| 1.5.0   | 2025-12-15 | Bug fixes, performance     |

Tips for Readable Source

Tables in markdown source can get messy fast. A few habits help:

1. Align pipes vertically. Most editors have a “format table” command or extension. In VS Code, search the marketplace for “Markdown Table Formatter.”
2. Keep cell content short. If a cell needs more than a few words, consider whether a table is the right format.
3. Use consistent alignment. Pick left-aligned for text, right-aligned for numbers, and stick with it.

Build and Share Tables

Write your tables in the MDtoLink editor, see them rendered in real time, then publish the document to a shareable URL. The editor handles GFM tables out of the box, so what you see in the preview is what your readers will see.