Markdown to Confluence: Wiki Markup Cheat Sheet

Migrating technical documentation from Git repositories to Atlassian Confluence often leads to a formatting mismatch. Developers write in standard Markdown, but Confluence utilizes its own markup syntax.

In the Confluence Data Center and Server editor, Atlassian documents in Atlassian: Confluence wiki markup that you can insert both Confluence wiki markup and Markdown directly via the Insert Markup dialog (accessible via Ctrl+Shift+D or Cmd+Shift+D in the Data Center editor). Confluence converts it to rich text, and you cannot edit it as markup afterwards. Since Confluence Cloud’s editor differs, you may need to check your specific edition.

If you need to manually map syntax or convert documentation for automated scripts, this cheat sheet breaks down how common formatting elements map to Confluence Wiki Markup.

Markdown to Confluence Mapping Table

Here is a quick reference for mapping common Markdown elements to Confluence Wiki Markup.

Note: In Confluence, table headers use double pipes and data cells use single pipes. Links are formatted as [Link Text|URL].

For links, Markdown uses [Text](URL), while Confluence uses brackets separated by a pipe: [Text|URL]. For multi-paragraph quotes, use {quote}...{quote} instead of bq..

For table headers, Markdown uses a row of dashes separated by pipes, while Confluence uses double pipes for header cells: || Header || Header ||.

Code Blocks and Inline Code

Code blocks are critical for developer documentation. Markdown uses triple backticks, while Confluence wraps the code in {code} tags.

Markdown Code Block:

```javascript
const greeting = "Hello World";
console.log(greeting);
```

Confluence Code Block:

{code:javascript}
const greeting = "Hello World";
console.log(greeting);
{code}

Inline Code Mapping:

Markdown: Use the `POST` method.
Confluence: Use the {{POST}} method.

Tables

Tables are the most tedious elements to convert manually. Markdown requires a separator row (|---|---|) to define headers, while Confluence dictates headers by using double pipes (||) instead of single pipes.

Markdown Table:

| Endpoint | Method | Description |
|----------|--------|-------------|
| /users   | GET    | List users  |

Confluence Table:

|| Endpoint || Method || Description ||
| /users | GET | List users |

Developer CLI Alternative: Pandoc

If you are building an automated pipeline that synchronizes Git repositories with Confluence, you can use pandoc to convert Markdown to Jira/Confluence wiki markup programmatically.

As documented in the pandoc manual, the jira format in pandoc produces correct wiki markup (including headings, links, inline code, code blocks, and tables), but it adds an {anchor:...} tag to every heading.

You can use the following pipeline to convert Markdown and clean up the anchor tags:

pandoc input.md -f gfm -t jira | sed -E 's/\{anchor:[^}]*\}//' > output.txt

Example output from pandoc:

h3. API Architecture
See [View Repository|https://github.com/example/repo/] and use the {{POST}} method.

{code:javascript}
const greeting = "Hello World";
{code}
|| Endpoint || Method || Description ||
| /users | GET | List users |

Gotchas

• Anchor Tags: pandoc adds {anchor:...} to headings, which are stripped by the sed step above.
• Task Lists: Markdown task lists (- [ ] item) have no direct equivalent in Confluence wiki markup.
• Nested Lists: Nested lists use **, ##, or *# style prefixes in wiki markup rather than indentation.

Client-Side Conversion

If you have a large documentation file and prefer a visual tool over the CLI, you can use the Markdown to Confluence Converter. It is a local-first browser utility that instantly transforms standard Markdown into valid Confluence Wiki Markup without uploading your proprietary logic or internal documentation to an external server.