Moving a GitHub wiki to Confluence Cloud (and when not to move it)

Mesut Sözüer — Fri, 30 Oct 2026 11:06:53 +0000

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:

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.
In Confluence, insert SourceDocs: File from Git, paste the link, and click Preview.
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.

DEV Community: Mesut Sözüer