Markdown Tables in Confluence and Jira: Paste, Wiki Markup and Line Breaks

How do I get a Markdown table into Confluence or Jira?

Atlassian products have changed their editors more than once, so this page separates what is stable (the wiki-markup syntax) from what varies by product and version (paste behavior). Where it varies, test with a two-row table before moving a large one.

| Key  | Status |
| :--- | :----- |
| WEB-1 | Done   |
| WEB-2 | Open   |

||Key||Status||
|WEB-1|Done|
|WEB-2|Open|

Pasting into the Confluence Cloud and Jira Cloud editors

Confluence Cloud and Jira Cloud use Atlassian's rich-text editor. It stores a document structure rather than Markdown, and it accepts structured content on paste. What that means in practice:

• A rendered table pastes as a table. Render the Markdown (a GitHub preview, VS Code preview or this site's Markdown table to HTML output), select the table, copy and paste. Header cells usually stay header cells.
• Cells from a spreadsheet paste as a table. Convert the table to tab-separated text with the Markdown table to TSV tool, paste it into Excel or Google Sheets, then copy the cells into the page. The copy-to-Word, Excel and Google Docs guide has the spreadsheet steps.
• Markdown text on paste. The editors convert Markdown-style shortcuts as you type and have converted some pasted Markdown, but Atlassian has changed this over time and reports of pasted pipe tables staying as plain text are common. Treat it as unreliable until you have tried it on your own site.
• Marketplace apps. Several Markdown macros exist for Confluence. Availability and behavior depend on the app and on your site's admin settings, so check what your organization allows.

Wiki markup tables: ||header|| and |cell|

Wiki markup is the older Atlassian text format. It is still used in Jira fields that render with the wiki-style renderer, in Confluence Data Center's markup dialog (Ctrl+Shift+D, or Cmd+Shift+D on a Mac), and in the Jira REST API v2. The rules for tables:

• ||Header||Header|| is a header row. Each header cell is wrapped in double pipes.
• |Cell|Cell| is a normal row. There is no delimiter row and no alignment syntax.
• An empty cell needs a space, | |; two pipes together are read as a header marker.
• A row header is ||Label|value|value|: the first cell is a header, the others are data. Check the preview to confirm.
• One row per line. A blank line ends the table.

||Key||Status||
|WEB-1|Done|
|WEB-2|Open|

||Environment||Staging||Production||
||Region|eu-west-1|us-east-1|
||Replicas|2|6|

Writing these by hand is error-prone for anything more than a few rows. Paste the Markdown into Markdown table to Jira or Markdown table to Confluence to get wiki markup with the escaping done. If you are starting from scratch, Markdown table syntax explains the source format.

Converting Markdown cell content to wiki markup

Cell content has its own syntax, and several Markdown habits don't carry over:

| Name          | Link                                  | Code     |
| :------------ | :------------------------------------ | :------- |
| **Release 4.2** | [Notes](https://example.com/notes) | `npm ci` |

||Name||Link||Code||
|*Release 4.2*|[Notes|https://example.com/notes]|{{npm ci}}|

Check the result in the field's preview before saving. The link syntax [text|url] contains a pipe; the renderer normally reads it as a link inside a cell, but if a link breaks the row, escape that pipe as \|.

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

• Cloud editors (Confluence and Jira): press Shift+Enter for a line break inside the cell, or Enter to start a new paragraph in the same cell. Cells can also hold lists and, in Confluence, macros.
• Wiki markup: write \\ where the line should break. Everything stays on one source line:

||Step||Notes||
|Deploy|Run the pipeline\\Check the logs|
|Verify|Open the health page|

• Markdown source with <br>: convert it with the tool above, which changes each <br> into \\. More on breaks in Markdown cells: line breaks in tables.

Escaping pipes and curly braces

Two characters are special inside a wiki-markup cell: | ends the cell, and { starts a macro or a formatting block ({code}, {noformat}, {{monospace}}). Escape them with a backslash. The same \| habit applies in Markdown; see escaping pipes in Markdown tables.

||Command||Meaning||
|{{grep -E "a\|b" app.log}}|Match a or b|
|Use \{braces\} literally|Escaped braces|
|Empty cell next to this| |

Borders, width and styling in Confluence tables

Confluence table borders. Neither Markdown nor wiki markup can set a border, color or width. In the Cloud editor, a table's options cover a header row and column, numbered rows, cell background color, merge and split, and table width (default, wide or full width). The documentation does not list a border control, so if you need one, check your current editor and the apps your admin has installed. In Data Center, a site administrator can add table CSS in the site stylesheet, which affects every page.

Merged cells. Confluence tables can merge cells in the editor, but wiki markup tables cannot express merges. Make the table in the editor, or see merged cells in Markdown tables for what plain Markdown can do (it is HTML).

Wide tables. Set the table to wide or full width in the Cloud editor, or break the table into sections. The transpose tool helps when a table has many columns and few rows.

Tables through the REST API: ADF and storage format

For bots, migrations and automation, build the table in the format the API expects:

• Jira Cloud REST API v3 takes Atlassian Document Format (ADF) for rich text fields such as the description and comments. A table is a table node with tableRow children, which contain tableHeader and tableCell nodes, each holding a paragraph:

{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "table",
      "attrs": { "isNumberColumnEnabled": false, "layout": "default" },
      "content": [
        {
          "type": "tableRow",
          "content": [
            { "type": "tableHeader", "attrs": {}, "content": [
              { "type": "paragraph", "content": [{ "type": "text", "text": "Key" }] } ] },
            { "type": "tableHeader", "attrs": {}, "content": [
              { "type": "paragraph", "content": [{ "type": "text", "text": "Status" }] } ] }
          ]
        },
        {
          "type": "tableRow",
          "content": [
            { "type": "tableCell", "attrs": {}, "content": [
              { "type": "paragraph", "content": [{ "type": "text", "text": "WEB-1" }] } ] },
            { "type": "tableCell", "attrs": {}, "content": [
              { "type": "paragraph", "content": [{ "type": "text", "text": "Done" }] } ] }
          ]
        }
      ]
    }
  ]
}

• Jira REST API v2 accepts the wiki-markup string used in this guide.
• Confluence storage format is XHTML. It needs well-formed XML, so self-close tags such as <br />. Start from the output of Markdown table to HTML and check it against Atlassian's storage-format documentation:

<table>
  <tbody>
    <tr><th><p>Key</p></th><th><p>Status</p></th></tr>
    <tr><td><p>WEB-1</p></td><td><p>Done<br />Reviewed</p></td></tr>
  </tbody>
</table>

Confirm field and endpoint details in Atlassian's current API documentation; the formats evolve with each version.

Common problems

If the Markdown itself is the problem, check it in the Markdown table validator first. Tables for other platforms are in the GitHub and GitLab guides.

Frequently asked questions