Confluence to GitHub or GitLab: keep docs as Markdown in git

Published 2026-10-17 · Facts checked 2026-10-17 · By ArtUp Labs, the maker of ArtUp Export

1. Decide which side is the source

• Moving off Confluence. Export once, commit, and from then on edit in git. Freeze or archive the space so nobody keeps writing there.
• Publishing from Confluence. Writers stay in Confluence; the repository is a published copy that you refresh. Treat the docs folder as generated and do not edit it by hand — the next export would overwrite the edits.

Confluence's own export (HTML, PDF, CSV, XML for a space) has no mode that exports only changed pages. Source: Atlassian, Export content, checked 2026-10-17. If you convert the HTML export, the second route means repeating the full conversion each time — see how to export a space to Markdown.

2. The first export

1. Export the space (or the branch you publish) to Markdown and download the zip. With ArtUp Export: space sidebar → ArtUp Export → Whole space → your preset → Export.
2. Unzip it into the repository and commit:

   git switch -c docs-import
   unzip -o artup-export-DOCS-2026-10-17.zip -d docs
   git add docs && git commit -m "Import Confluence space DOCS"

3. Keep the zip, or at least its export-manifest.json: it holds the ids, versions and paths of the pages (no content) and is what the next update starts from.

3. Every next time: only what changed

1. In ArtUp Export choose Update previous export and drop in the previous zip or its export-manifest.json.
2. The new zip holds new and changed pages with their attachments, the new manifest, and export-deleted.txt with the paths of renamed, moved and deleted pages.
3. Apply it next to the docs folder — the result screen shows this command with your zip's name and a Copy button:

   unzip -o <zip> -d docs && cd docs && if [ -f export-deleted.txt ]; then while IFS= read -r f; do rm -f -- "$f"; done < export-deleted.txt; rm -f export-deleted.txt; fi

4. Review and commit, or open a merge request:

   git status
   git add -A docs && git commit -m "Update docs from Confluence"

Measured On a 1,001-page test space (29 September 2026): a second full export with no changes was byte-identical, and git status after unzipping it over the committed tree reported nothing to commit, working tree clean. After three edits, one rename, one move and one deletion, the update export took 137 seconds and was 2.1 MB; applied over the first export it gave exactly the same 1,201 files as a fresh full export.

4. How the files look on GitHub and GitLab

• Front-matter (title, Confluence id, version, labels, page URL) sits at the top of every file; static site generators read it, and you can trace each file back to its page.
• Links between pages are relative .md paths, so they work in the GitHub and GitLab file browsers. Links to pages outside the export point back to Confluence.
• Panels in the Generic Markdown preset are written as GitHub alerts (> [!NOTE]), which GitHub renders as callouts (GitHub Docs). Other renderers show them as a quote with the marker; check your GitLab version, or choose the Docusaurus or MkDocs preset if you publish with those.
• Tables with merged cells are kept as HTML; GitHub renders them, and so do Docusaurus and MkDocs with the settings in our documentation.

One limit to plan for: the export runs in your browser, not in CI. Someone clicks Export; the rest — apply, commit, review, publish — can be your usual pipeline.