How to Add a Line Break in a Markdown Table Cell

How do I add a new line in a table cell?

Write the whole row on one line and insert <br> at each break. Stack as many as you need.

| Environment | Server                                   |
| :---------- | :--------------------------------------- |
| Production  | AWS us-east-1<br>8 vCPU, 32 GB RAM<br>gp3 SSD |
| Staging     | AWS us-west-2<br>2 vCPU, 8 GB RAM<br>gp3 SSD  |

<br>, <br/> and <br /> are equivalent in HTML. Use <br /> if your Markdown goes through MDX (see below); otherwise pick one and stay consistent. The table formatter keeps the tags intact when it pads the columns.

Why pressing Enter breaks the table

In GitHub Flavored Markdown each line of the source is one table row. A newline inside a cell doesn't continue the cell; it ends the row, and the text after it becomes a new row (or ends the table if there is no pipe on the line). The usual Markdown hard breaks, two trailing spaces or a trailing backslash, don't apply either, because they need a newline after them. That leaves inline HTML, which the parser passes through as part of the cell.

Every way to get multiple lines in a cell

Worked examples

Multiline header

Long headers make every row wide. Breaking the header moves the unit or qualifier onto a second line and keeps the column narrow.

| Region | Revenue<br>(USD, millions) | Growth<br>(year over year) |
| :----- | -------------------------: | -------------------------: |
| Europe |                      12.40 |                      +8.1% |
| Asia   |                       9.75 |                     +14.6% |

Code on several lines

A code span shows its contents literally, so <br> inside backticks prints as text. Close the code span before each break, or use the HTML <code> element, which does allow <br> inside it.

| Task   | Commands                                   |
| :----- | :----------------------------------------- |
| Deploy | `git checkout main`<br>`npm run deploy`    |
| Test   | <code>npm ci<br>npm test</code>             |

Paragraphs in a cell

| Decision | Rationale |
| :------- | :-------- |
| Use PostgreSQL | Mature JSON support.<br><br>The team already runs it in production. |

Lists in a cell

Markdown list markers (-, 1.) can't start a line inside a cell, so lists need HTML. On GitHub and GitLab, an inline <ul> or <ol> works if the whole list is on the row's line. Text bullets with <br> are the fallback for renderers that strip list tags.

| Plan | Includes |
| :--- | :------- |
| Pro  | <ul><li>Unlimited tables</li><li>Custom CSS export</li></ul> |
| Team | • Everything in Pro<br>• Shared workspaces |

Stopping a line from wrapping

The opposite problem: renderers wrap long cells to fit the page, which can split a command or a name. Replace the spaces that must not break with  . Entities are not decoded inside backtick code spans, so for code use the HTML <code> element instead, or give the column more room (see column width).

| Command | Effect |
| :------ | :----- |
| <code>git&nbsp;push&nbsp;--force-with-lease</code> | Push, but refuse if the remote moved |
| git&nbsp;push&nbsp;origin&nbsp;main | Push the main branch |

Line break support by platform

Hugo shows nothing where the <br> was

Hugo's Markdown renderer, Goldmark, drops raw HTML by default and leaves an <!-- raw HTML omitted --> comment in its place, so the two lines run together. Enable raw HTML in the site config:

# hugo.toml
[markup.goldmark.renderer]
  unsafe = true

# hugo.yaml
markup:
  goldmark:
    renderer:
      unsafe: true

“Unsafe” means Hugo stops filtering any HTML in your content. That is fine for a site where you write the Markdown yourself; think twice if the content comes from untrusted contributors.

Docusaurus and MDX: write <br />

Docusaurus compiles .md and .mdx files with MDX by default, and MDX treats HTML as JSX, where every tag must be closed. An unclosed <br> fails the build with an error about a missing closing tag. Use the self-closing form:

| Step    | Details                         |
| ------- | ------------------------------- |
| Install | Download it<br />Run setup      |

The same applies to Next.js MDX, Astro MDX and any other MDX pipeline.

ChatGPT, Cursor and other chat UIs show <br> as text

AI chat interfaces render Markdown tables but often don't render raw HTML, so a table with <br> may display the tag as text there. If you are asking a model for a table you will read in the chat, ask it to avoid HTML and keep one value per cell, or separate items with semicolons. If the table is going into a README or docs, the <br> version is right; it will render once it is on GitHub or your site.

Real multiline cells: Pandoc grid tables

Pandoc (and Quarto, which uses it) is the one widely used toolchain with true multiline cells. In a grid table each cell is a small Markdown document: blank lines make paragraphs, and lists and code blocks work.

+---------+---------------------------+
| Step    | Details                   |
+=========+===========================+
| Install | Run the installer.        |
|         |                           |
|         | Restart when it finishes. |
+---------+---------------------------+
| Ship    | - Tag the release         |
|         | - Publish the notes       |
+---------+---------------------------+

Pandoc's multiline tables also let a row span several source lines, but the lines are joined into one paragraph, so they help with long text rather than hard breaks. In pipe tables, Pandoc treats <br> as raw HTML: it reaches HTML output and is dropped from LaTeX, PDF and Word output. The Pandoc tables guide covers all four table styles.

Pasting cells with line breaks from Excel or Sheets

A spreadsheet cell with a line break inside (Alt+Enter in Excel, Ctrl+Enter in Google Sheets) is copied as a quoted value containing a real newline. Paste that into a hand-written table and the row splits in two. The Excel to Markdown converter and the CSV converter turn those newlines into <br> for you, so paste the cells there instead.

Common mistakes (broken vs. fixed)

Pressing Enter inside a cell

| Step | Task |
| :--- | :--- |
| 1    | Download installer
Run setup wizard |
| 2    | Launch the app |

| Step | Task |
| :--- | :--- |
| 1    | Download installer<br>Run setup wizard |
| 2    | Launch the app |

Typing \n

| Name | Description     |
| :--- | :-------------- |
| Auth | Step 1\nStep 2 |

A break inside backticks

| Task  | Commands                     |
| :---- | :--------------------------- |
| Build | `npm ci<br>npm run build` |

| Task  | Commands                         |
| :---- | :------------------------------- |
| Build | `npm ci`<br>`npm run build` |

The table validator catches rows that were split by a stray newline.

When to switch to an HTML table

<br> is right for two or three short lines. When a cell needs real structure, such as numbered steps, a fenced code block or several paragraphs, write the table in HTML. On GitHub and GitLab you can still use Markdown inside a <td> if you leave a blank line after the opening tag and before the closing one:

<table>
  <tr>
    <th>Step</th>
    <th>Details</th>
  </tr>
  <tr>
    <td>Install</td>
    <td>

1. Download the installer.
2. Run it.

```sh
./install.sh --prefix ~/.local
```

</td>
  </tr>
</table>

Other options: move the detail out of the table and link to it, or hide a long table in a collapsible section. For pipes inside cells, see escaping pipes; for everything else, the Markdown table syntax guide.

Frequently asked questions