Markdown in Confluence Cloud in 2026: what actually works

"Does Confluence support Markdown?" gets asked every week, and the answers you find are often from the old editor or from Confluence Server. Here is where Confluence Cloud stands in late 2026, tested rather than remembered.

TL;DR

You want to...	Built in?	What to do
Edit a page as Markdown	No	There is no Markdown mode
Type Markdown-style shortcuts	Yes	#, **, backticks, *, >, [] while typing
Paste a Markdown document	Yes, and it works well	Paste the raw text
Import .md files	No	Paste, script the REST API, or convert to HTML
Show Markdown that lives in Git	No	Render it with an app, or republish from CI
Get Mermaid/PlantUML diagrams	No	Needs an app

1. There is no Markdown mode

You cannot switch a page to Markdown and edit the source. Typing /markdown in the editor only lists Markdown macros from installed apps (and the keyboard-shortcut help). Whatever you do, the page ends up as Confluence rich text.

2. The shortcuts are real, and they are Markdown

While typing, the editor converts:

• # to ###### plus a space into headings
• **bold**, *italic*, ~~strike~~, `code`
• * or 1. plus a space into lists, > into a quote, three backticks into a code block, --- into a divider
• [] into an action item, [text](url) into a link

Press Ctrl+/ in the editor for the full list. If your fingers already think in Markdown, this covers most daily writing.

3. Pasting Markdown is better than its reputation

Older threads say pasting Markdown gives you a wall of text. That is no longer true. Paste the raw Markdown (not the rendered preview) and Confluence converts it. In our test in October 2026, these all came through:

• headings, bold, italic and inline code
• bulleted and numbered lists
• tables
• fenced code blocks
• quotes
• task lists
• links

What does not:

• mermaid and plantuml code fences stay as code blocks showing the source.
• The result is a copy. You cannot edit it as Markdown later, and it does not change when the original file changes.

That makes paste the best option for one-off content: an AI assistant's answer, a design note from your editor, a README you want to quote once.

4. Importing .md files: still no importer

Settings → Import from other tools handles Notion, Miro, Mural and HTML files. Markdown is not on the list. Your options:

• A few files: paste them, as above.
• Many files, once: a script against the Confluence REST API, or an open-source publisher like mark or md2conf. Alternatively convert to HTML (pandoc works) and use the HTML import.
• Files that keep changing: don't import them at all. See the next section.

5. When the Markdown lives in a repository

This is the case most engineering teams actually have: README files, runbooks, ADRs and API docs that live next to the code and change with it. Importing them creates a copy that goes stale.

Two patterns avoid that:

Republish from CI. A pipeline step converts the Markdown and overwrites the Confluence page on every merge. You get real Confluence pages, fully searchable. The costs are pipeline setup, a service account with write access, and pages that people must not edit by hand, because the next run overwrites them.

Render the file on the page. A macro on the Confluence page fetches the file from the repo and renders it whenever someone opens the page. Nothing is copied, so nothing goes stale. Readers do not need Git access. One thing to check with any tool in this category: whether Confluence search finds words from inside the file. Many macros draw inside an iframe that search cannot read.

Disclosure: I build SourceDocs, an app in the second category. You paste a file link from GitHub, GitLab, Bitbucket or Azure DevOps (private repos via one read-only token). It renders Markdown including mermaid and plantuml code fences as diagrams, and saves a plain-text copy with the macro so Confluence search finds the page. It also has a Markdown macro for writing Markdown in the page with live preview, if you want the source to stay editable as Markdown.

6. Quick decision guide

• Writing new content in Confluence → use the shortcuts.
• Moving a document in once → paste raw Markdown.
• Moving hundreds of files once → script or CLI publisher.
• Content that changes in Git → republish from CI, or render it live; don't copy it by hand.

---

I keep a longer, regularly re-tested reference here: Markdown in Confluence Cloud. If you have found a paste case that breaks, tell me in the comments and I'll add it.