Markdown to Confluence: Why Your Pasted Notes Break and How to Fix Them

You write everything in Markdown. Your README, your release notes, your incident timeline, the half-finished spec in Obsidian — all of it is hashes, asterisks, and triple-backtick fences. Then your team lives in Confluence, and the moment you paste that clean Markdown into a page, it falls apart. The headings stay as literal ##. The bold text keeps its asterisks. Your code block becomes a wall of backticks with no panel around it. This is the single most common reason a Markdown writer's work looks broken in a company wiki, and the fix is understanding that Confluence does not speak Markdown. It speaks its own wiki markup.

Confluence has its own syntax, and it is not Markdown

Atlassian's older notation is called wiki markup, and you reach it inside a page through Insert, then Markup, then Wiki Markup. The modern Confluence editor will sometimes auto-detect a heading or a bold run as you type, but that behavior is inconsistent across Cloud, Server, and Data Center, and it gives up entirely on code blocks, tables, and nested lists. So the reliable path is to convert your Markdown into wiki markup first, then paste it through that Markup dialog. The page interprets the tokens and renders real headings, real panels, and real tables.

The headings are the clearest example of the gap. Markdown counts hashes; Confluence uses a named token. A # Title line does not become a big heading on its own — it has to be rewritten as h1. Title. Two hashes, ## Section, becomes h2. Section, and the pattern continues down to h6.. The letter h, the level number, a dot, then a space before your text. That h1. form is the heart of the difference, and once you see it the rest of the markup feels familiar.

The conversion rules, construct by construct

Here is the mapping that actually matters when you move a document over. Most of these are one-to-one substitutions, which is why a converter can handle them with plain text rules:

• A heading ## Plan becomes h2. Plan. Trailing hashes used for symmetry (## Done ##) get stripped, so you do not end up with stray characters.
• Bold **text** collapses to a single asterisk: *text*.
• Italic _text_ stays as _text_, carried by underscores.
• An inline ` npm run build becomes the double-brace monospace token {{npm run build}}`.
• A link [docs](https://example.com) flips to the pipe form [docs|https://example.com].
• Bullets become a single * marker; numbered items become a single # marker.
• A blockquote wraps in a {quote} block.
• A horizontal rule (---) becomes a ---- line.

The two that trip people up are code blocks and tables, so they each deserve their own section.

Code blocks: from triple backticks to brace panels

In Markdown a fenced block opens with three backticks and an optional language. In Confluence wiki markup that becomes a brace code panel. A block tagged bash turns into {code:bash} to open and {code} to close. A fence with no language becomes a plain {code} panel. The crucial detail is that the panel's contents pass through verbatim — an asterisk or a hash sitting inside your sample code is never mistaken for formatting, because the converter treats everything between the braces as literal.

That verbatim handling is exactly what saves you when you paste a shell snippet full of flags, pipes, and quotes. Without it, your grep -E '\*' would get half-eaten by the bold and list rules.

A worked example

Take a small Markdown note like the one you might draft for a release page:

## Deploy steps

Run the build, then ship:

`pnpm build`

| Stage | Owner |
| ----- | ----- |
| Build | Ada   |
| Ship  | Li    |

Run that through the Markdown to Confluence converter and it comes back as wiki markup:

h2. Deploy steps

Run the build, then ship:

{{pnpm build}}

||Stage||Owner||
|Build|Ada|
|Ship|Li|

Notice three things. The heading became h2.. The inline code became {{pnpm build}}. And the table dropped its dashed separator row entirely — Confluence does not use one — while the header row picked up double bars (||Stage||Owner||) and the body rows use single bars. Those double bars are how wiki markup marks a heading row, which is why the result renders with a bold top row instead of a line of stray pipes.

Tables, and the double-bar header

Tables are worth lingering on because the Markdown and Confluence models look similar but differ in two ways. Markdown wants a header row, a dashed separator row, then body rows. Confluence wants no separator row at all, header cells wrapped in ||, and body cells wrapped in single |. So | Name | Role | over a | --- | --- | separator becomes ||Name||Role|| with the separator gone, and | Ada | Engineer | becomes |Ada|Engineer|. Get the bar count wrong and Confluence shows literal pipe characters, which is the exact failure people hit when they paste raw Markdown and assume the table will survive.

Confluence is not Jira

One footgun worth naming: Confluence and Jira share most tokens, so it is easy to assume they are interchangeable. They mostly are — the same h1. headings, *bold*, _italic_, {{monospace}}, and {code} panels work in both. The one place they split is the blockquote. Jira prefixes every quoted line with bq., while Confluence wraps the whole quote in a single {quote} block. Paste Jira-style bq. lines into a Confluence page and they will not render as a quote at all. If your target is actually Jira, reach for the Markdown to Jira tool instead, which applies the bq. form per line. Knowing which side you are on saves a confusing round of "why is this quote plain text."

How I actually use this

I keep my own engineering notes in Markdown because it is fast and it is the same syntax I get back from chat assistants and from GitHub. When a draft is ready to share with the wider team, I do not retype it into Confluence — I paste the whole thing into the converter, hit copy, and drop the wiki markup into the page through Insert, then Markup, then Wiki Markup. A recent postmortem went over in about ten seconds this way: the root-cause heading landed as h2., the log excerpt landed as a {code} panel, and the timeline stayed a real bulleted list. The thing I never do is share the tool's URL for confidential text, because the share link encodes the input in the query string and that text would land in the recipient's server access log. For a runbook or an unreleased spec, I use the copy button and paste the text directly.

When wiki markup is hidden

One last gotcha. The wiki markup path is a legacy feature, and some newer Confluence Cloud sites tuck the Insert, then Markup option behind admin settings. If you cannot find it, an admin can enable it, and the same menu then accepts pasted wiki markup. If your space is locked to the storage-format (XML) editor instead, note that this conversion produces wiki markup, not storage format — so paste it through the Markup dialog rather than the raw HTML editor. Everything runs client-side in your browser tab, nothing is uploaded, and the converted text is yours to copy and reuse anywhere a Confluence page will take it.

---

Made by Toolora · Updated 2026-06-13