Markdown in Confluence Cloud in 2026: what actually works
---
title: "Markdown in Confluence Cloud in 2026: what actually works"
published: true
description: "No Markdown mode, a surprisingly good paste conversion, no .md importer, and what to do when your Markdown lives in a Git repository."
tags: confluence, markdown, documentation, productivity
---
"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.
Moving a GitHub wiki to Confluence Cloud (and when not to move it)
---
title: "Moving a GitHub wiki to Confluence Cloud (and when not to move it)"
published: true
description: "Two practical paths from a GitHub wiki to Confluence Cloud: a one-time copy with git and paste, or showing the wiki pages live so nobody maintains two copies."
tags: confluence, github, documentation, markdown
---
Your engineers write in the GitHub wiki. Everyone else lives in Confluence. Sooner or later someone asks for "the wiki, but in Confluence", and you find out there is no importer for that.
There are two honest answers, and which one is right depends on a single question: where will people edit after the move?
- If the wiki is being retired and Confluence becomes the only place to edit, copy it once.
- If developers will keep editing on GitHub, don't copy it. Show the wiki pages inside Confluence instead, so there is still only one version.
Here is how to do each.
Path A: copy the wiki once
1. Get every page as a file
A GitHub wiki is a Git repository of its own. Clone it next to the main repo:
git clone https://github.com/OWNER/REPO.wiki.git
cd REPO.wiki
ls *.md # one file per page; Home.md is the start page
File names use hyphens where page titles have spaces, so Getting-Started.md is the page "Getting Started". _Sidebar.md and _Footer.md are the sidebar and footer, which you probably want to turn into a Confluence page tree rather than copy.
2. Find the wiki-only syntax before you paste
GitHub wikis allow links and images that no other Markdown tool understands:
grep -n "\[\[" *.md
Every hit is either a page link ([[Getting Started]], [[Read this first|Getting Started]]) or an embedded image ([[diagram.png]]). None of them convert on paste, so either rewrite them as normal Markdown links first, or note them down and fix them in Confluence afterwards with the link picker.
3. Paste
Confluence Cloud has no Markdown mode, but it converts Markdown when you paste it. In our test (October 2026), headings, lists, tables, task lists, fenced code blocks, quotes and links all came through. Open a file, copy the raw text, paste it into a new page.
Two things do not survive:
- `mermaid and `plantuml blocks arrive as code blocks showing the source, not as diagrams.
- Images stay pointed at GitHub. Upload them to the Confluence page if the wiki is going away.
4. More than a few dozen pages?
Confluence's importer (Settings → Import from other tools) covers Notion, Miro, Mural and HTML, not Markdown. For a big wiki, script it against the Confluence REST API, or use an open-source publisher such as mark or md2conf. They create one page per file. They will not fix [[wiki links]] for you, so do step 2 first.
5. Close the old copy
Once the pages are in Confluence, turn the wiki off or restrict who can edit it (repository Settings → General → Features). Two editable copies drift apart within weeks.
Path B: keep the wiki on GitHub and show it in Confluence
This is the right choice when the wiki is maintained by the people who write the code. Moving it would just add a second place to update.
The idea: each Confluence page that should contain a wiki page gets a macro that renders the wiki page from GitHub every time someone opens it. You arrange those Confluence pages in a tree however you like, link to them from your project spaces, and the content stays exactly what is on GitHub.
Disclosure: I build SourceDocs, a Confluence Cloud app that does this. Other ways to get the same effect exist (a CI job that republishes pages, for example); this is the approach I know best.
With SourceDocs it looks like this:
1. Open the wiki page on GitHub and copy the address, e.g. https://github.com/OWNER/REPO/wiki/Getting-Started. The wiki's own address shows its Home page.
2. In Confluence, insert SourceDocs: File from Git, paste the link, and click Preview.
3. Save. Edits on the wiki show up within 10 minutes, or immediately with Refresh.
What carries over:
- [[Page Name]] and [[Text|Page Name]] become working links, [[image.png]] shows the image.
- Tables, task lists, highlighted code, GitHub alerts, and `mermaid / `plantuml blocks drawn as real diagrams.
- Confluence search finds the page by the wiki text: a plain-text copy is saved with the macro and refreshed whenever the macro is saved.
- PDF and Word export print the wiki page as real headings, lists and tables.
Limits worth knowing before you commit: wikis of public repositories work without setup; for private repositories, ask first (I'd rather tell you than have you find out). Wikis on GitHub Enterprise Server are not supported yet, and pages written in AsciiDoc or other markup show as source.
Which one should you pick?
| | Copy once | Show live |
|---|---|---|
| Where people edit | Confluence | GitHub wiki |
| Stays current | Only if someone re-copies | Always |
| Confluence search | Yes | Yes (text saved with the macro) |
| Page history | Confluence | Git |
| Effort | Per page, plus link fixing | One link per page |
| Good for | Retiring the wiki | Wikis developers keep editing |
If you are unsure, ask your developers whether they will keep using the wiki. If the answer is yes, a copy will be out of date by the next sprint.
---
A longer reference lives here: GitHub wiki to Confluence Cloud. Questions are welcome in the comments.
Mentions
Markdown in Confluence Cloud in 2026: what actually works --- title: "Markdown in Confluence Cloud in 2026: what actually works" published: true description: "No Markdown mode, a surprisingly good paste conversion, no .md importer, and what to do when your Markdown lives in a Git repository." tags: confluence, markdown, documentation, productivity --- "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.
Moving a GitHub wiki to Confluence Cloud (and when not to move it) --- title: "Moving a GitHub wiki to Confluence Cloud (and when not to move it)" published: true description: "Two practical paths from a GitHub wiki to Confluence Cloud: a one-time copy with git and paste, or showing the wiki pages live so nobody maintains two copies." tags: confluence, github, documentation, markdown --- Your engineers write in the GitHub wiki. Everyone else lives in Confluence. Sooner or later someone asks for "the wiki, but in Confluence", and you find out there is no importer for that. There are two honest answers, and which one is right depends on a single question: where will people edit after the move? - If the wiki is being retired and Confluence becomes the only place to edit, copy it once. - If developers will keep editing on GitHub, don't copy it. Show the wiki pages inside Confluence instead, so there is still only one version. Here is how to do each. Path A: copy the wiki once 1. Get every page as a file A GitHub wiki is a Git repository of its own. Clone it next to the main repo: git clone https://github.com/OWNER/REPO.wiki.git cd REPO.wiki ls *.md # one file per page; Home.md is the start page File names use hyphens where page titles have spaces, so Getting-Started.md is the page "Getting Started". _Sidebar.md and _Footer.md are the sidebar and footer, which you probably want to turn into a Confluence page tree rather than copy. 2. Find the wiki-only syntax before you paste GitHub wikis allow links and images that no other Markdown tool understands: grep -n "\[\[" *.md Every hit is either a page link ([[Getting Started]], [[Read this first|Getting Started]]) or an embedded image ([[diagram.png]]). None of them convert on paste, so either rewrite them as normal Markdown links first, or note them down and fix them in Confluence afterwards with the link picker. 3. Paste Confluence Cloud has no Markdown mode, but it converts Markdown when you paste it. In our test (October 2026), headings, lists, tables, task lists, fenced code blocks, quotes and links all came through. Open a file, copy the raw text, paste it into a new page. Two things do not survive: - `mermaid and `plantuml blocks arrive as code blocks showing the source, not as diagrams. - Images stay pointed at GitHub. Upload them to the Confluence page if the wiki is going away. 4. More than a few dozen pages? Confluence's importer (Settings → Import from other tools) covers Notion, Miro, Mural and HTML, not Markdown. For a big wiki, script it against the Confluence REST API, or use an open-source publisher such as mark or md2conf. They create one page per file. They will not fix [[wiki links]] for you, so do step 2 first. 5. Close the old copy Once the pages are in Confluence, turn the wiki off or restrict who can edit it (repository Settings → General → Features). Two editable copies drift apart within weeks. Path B: keep the wiki on GitHub and show it in Confluence This is the right choice when the wiki is maintained by the people who write the code. Moving it would just add a second place to update. The idea: each Confluence page that should contain a wiki page gets a macro that renders the wiki page from GitHub every time someone opens it. You arrange those Confluence pages in a tree however you like, link to them from your project spaces, and the content stays exactly what is on GitHub. Disclosure: I build SourceDocs, a Confluence Cloud app that does this. Other ways to get the same effect exist (a CI job that republishes pages, for example); this is the approach I know best. With SourceDocs it looks like this: 1. Open the wiki page on GitHub and copy the address, e.g. https://github.com/OWNER/REPO/wiki/Getting-Started. The wiki's own address shows its Home page. 2. In Confluence, insert SourceDocs: File from Git, paste the link, and click Preview. 3. Save. Edits on the wiki show up within 10 minutes, or immediately with Refresh. What carries over: - [[Page Name]] and [[Text|Page Name]] become working links, [[image.png]] shows the image. - Tables, task lists, highlighted code, GitHub alerts, and `mermaid / `plantuml blocks drawn as real diagrams. - Confluence search finds the page by the wiki text: a plain-text copy is saved with the macro and refreshed whenever the macro is saved. - PDF and Word export print the wiki page as real headings, lists and tables. Limits worth knowing before you commit: wikis of public repositories work without setup; for private repositories, ask first (I'd rather tell you than have you find out). Wikis on GitHub Enterprise Server are not supported yet, and pages written in AsciiDoc or other markup show as source. Which one should you pick? | | Copy once | Show live | |---|---|---| | Where people edit | Confluence | GitHub wiki | | Stays current | Only if someone re-copies | Always | | Confluence search | Yes | Yes (text saved with the macro) | | Page history | Confluence | Git | | Effort | Per page, plus link fixing | One link per page | | Good for | Retiring the wiki | Wikis developers keep editing | If you are unsure, ask your developers whether they will keep using the wiki. If the answer is yes, a copy will be out of date by the next sprint. --- A longer reference lives here: GitHub wiki to Confluence Cloud. Questions are welcome in the comments.