BlueConfetti

FLINT MARKDOWN EXPORT · USE CASE

Move a Confluence documentation tree into a Git repository

Turn a Confluence page tree into Markdown files you can review, diff and commit like the rest of your documentation.

Finished result

A docs/handbook/ folder on a review branch, with one Markdown file per page, page-ID paths, relative links, a local image and a manifest. In the sample, one edit in Confluence changes exactly three files: the edited page, all-pages.md and manifest.json.

Before you start

Example: a five-page engineering handbook

The sample uses the same fictional handbook as the interactive demo: Engineering Handbook (page 1001) with Onboarding (1002) and its child First week (1003), Architecture overview (1004) with a diagram and a merged-cell table, and Release checklist (1005), which contains a Jira issue list.

Export the tree

  1. Open Engineering Handbook in Confluence and choose Apps → Export to Markdown. In Source, choose This page and descendants. Every accessible page in the tree starts selected; keep all five.
  2. Under Where will this Markdown go?, choose Git documentation. It uses relative Markdown links, page-ID filenames and blockquote panels, and leaves the export time out of each page’s frontmatter.
  3. Choose Review selection → Prepare full preview. Release checklist shows one conversion warning, Jira issue list not exported (JQL: project = ENG AND resolution = Unresolved); decide whether that is acceptable before you continue.
  4. Choose Build ZIP from preview, then Download ZIP. The sample archive is ENG-1001-2026-11-02.zip: the space key, the top folder and the export date.

Extract it on a review branch

Run these from the repository root, replacing the ZIP path with wherever you saved the download. Keep the ZIP itself outside the repository.

git switch -c confluence-export-2026-11-02
mkdir -p docs
unzip -q ~/Downloads/ENG-1001-2026-11-02.zip -d docs
mv docs/1001 docs/handbook
git add docs/handbook
git status --short

Git lists eight new files:

A  docs/handbook/1001.md
A  docs/handbook/1001/1002.md
A  docs/handbook/1001/1002/1003.md
A  docs/handbook/1001/1004.assets/system-overview.svg
A  docs/handbook/1001/1004.md
A  docs/handbook/1001/1005.md
A  docs/handbook/all-pages.md
A  docs/handbook/manifest.json

Each directory matches a parent page and each filename is a page ID, so a title change does not rename the file. Links between the exported pages are relative to the file that contains them. In 1001.md, the handbook links to [Onboarding](1001/1002.md); in 1001/1004.md, the diagram is ![System overview](1004.assets/system-overview.svg).

Commit the branch and review it the way you review other documentation changes:

git commit -m "Import Engineering Handbook from Confluence (2026-11-02)"

Refresh after a change in Confluence

In the sample, someone edits First week in Confluence, which publishes version 5. Once the import branch has been reviewed and merged into main, export the same tree with the same settings, then replace the exported folder on a new branch. Replacing the whole folder matters: pages that are no longer in the export show up as deletions instead of lingering in the repository. Start with a clean working tree and keep only generated export files in docs/handbook. The git rm command below removes tracked files and refuses to discard modified ones.

git switch main
git switch -c confluence-export-2026-11-03
git rm -r -- docs/handbook
unzip -q ~/Downloads/ENG-1001-2026-11-03.zip -d docs
mv docs/1001 docs/handbook
git add -A docs/handbook
git diff --cached --stat
 docs/handbook/1001/1002/1003.md | 11 ++++++-----
 docs/handbook/all-pages.md      |  7 ++++---
 docs/handbook/manifest.json     |  8 ++++----
 3 files changed, 14 insertions(+), 12 deletions(-)

The four untouched pages are byte-for-byte identical, because the Git documentation preset omits the per-page export timestamp. The edited page shows its new body and metadata:

-last_updated_by: "Sam Lee"
+last_updated_by: "Mei Tanaka"
 created: "2026-09-01T09:00:00.000Z"
-updated: "2026-10-08T15:30:00.000Z"
-version: 4
+updated: "2026-11-03T09:12:00.000Z"
+version: 5
 ...
-- Day 3 to 5: pair on the current sprint
+- Day 3 to 4: pair on the current sprint
+- Day 5: demo your first change at the team review
 ...
-npm test
+npm run check

manifest.json changes too: its exported time and the page’s version entry. all-pages.md repeats the edited text because it combines every page. Commit with a message that records the export date.

Sample files

Limits that affect this workflow

This guide checked that every relative link in the samples resolves to a file in the export. It did not observe how a particular Git hosting service renders these files.

Sample files on this page are fictional. They were produced by the released Flint Markdown Export exporter, using a simulated Confluence site instead of a live one. Interface labels come from the released app; this guide contains no app screenshots.