Guides / GitHub wiki

GitHub wiki to Confluence Cloud: copy the pages or show them live

A team that keeps its documentation in a GitHub wiki and its plans in Confluence ends up with two places to look. You can move the wiki into Confluence once, or leave it on GitHub and show its pages on Confluence pages, where they stay current.

Copy or show live?

• Copy once when the wiki is being retired and Confluence becomes the only place to edit.
• Show live when developers keep editing the wiki on GitHub and Confluence readers should always see the current version, without a second copy to maintain.

Copy the pages once

Confluence Cloud has no importer for GitHub wikis or Markdown files. A GitHub wiki is a Git repository of its own, so you can get all pages as Markdown files and paste them:

1. Clone the wiki: git clone https://github.com/org/repo.wiki.git. Each page is a .md file.
2. Open a file, copy its text and paste it into a new Confluence page. The editor converts Markdown headings, lists, tables, code blocks and links into Confluence formatting (see pasting Markdown).
3. Fix what does not convert: links written as [[Page Name]] stay as text, links between pages still point to GitHub, and images have to be uploaded to the Confluence page.

After that, the Confluence pages and the wiki are separate copies.

Show wiki pages live

1. Install SourceDocs for Confluence from the Atlassian Marketplace. A Confluence admin does this once for the site.
2. Open the wiki page on GitHub and copy the address from the browser bar, for example https://github.com/org/repo/wiki/Getting-Started. The address of the wiki itself (https://github.com/org/repo/wiki) shows the Home page.
3. Edit a Confluence page, type /git, pick SourceDocs: File from Git, paste the link and click Preview.
4. Save and publish. Edits on the wiki show up on the Confluence page within 10 minutes; Refresh fetches them immediately.

Put one macro on each Confluence page that should show a wiki page, and use Confluence's page tree to arrange them.

What works

• Wiki pages written in Markdown, rendered like the rest of SourceDocs: tables, task lists, code with syntax highlighting, alerts, and ```mermaid and ```plantuml blocks drawn as diagrams.
• Wiki links: [[Page Name]] and [[Link text|Page Name]] become links to that wiki page, and [[diagram.png]] shows the image. Ordinary relative links to other pages open them on GitHub.
• Images stored in the wiki and images linked from GitHub.
• PDF and Word export, with the wiki page as real Confluence headings, lists and tables.

Limits

• Wikis of public repositories work without any setup. If your wiki belongs to a private repository, write to [email protected] before you rely on it.
• Pages written in other markup languages that GitHub wikis allow (AsciiDoc, reStructuredText and others) are shown as source text.
• GitHub addresses wiki pages by name only. A page kept in a subfolder of the wiki repository is found through its raw address instead: https://raw.githubusercontent.com/wiki/org/repo/folder/Page.md.
• Wikis on GitHub Enterprise Server are not supported yet.

Questions

Can I show the wiki sidebar?

Yes, as its own macro: the sidebar is the page _Sidebar, so https://github.com/org/repo/wiki/_Sidebar shows it when the wiki has one.

Does Confluence search find the wiki text?

The page is shown live from GitHub, not copied, so Confluence's search indexes the page text around the macro but not the wiki page. Add a sentence or two above the macro with the words people will search for.

What does it cost?

Free for Confluence sites with up to 10 users. Above that, from 0.45 USD per user per month, with a 30-day free trial on the Marketplace.

More guides: Markdown in Confluence · Files from GitHub and GitLab in Confluence · Mermaid in Confluence · PlantUML in Confluence