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
- Flint Markdown Export installed with an active license, and permission to read the pages.
- A Git repository you can commit to, and your team’s usual review process. Flint creates a ZIP; it does not commit, push or open pull requests.
- Git on your computer. The commands below were run with Git 2.54.
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
- 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.
- 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.
- 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. - 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 --shortGit 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.jsonEach 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 .
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 checkmanifest.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
- ENG-1001-2026-11-02.zipFirst export: five pages, Git documentation preset.
- ENG-1001-2026-11-03.zipSecond export after the First week edit.
- handbook-2026-11-02-to-2026-11-03.diffThe complete Git diff between the two commits.
Limits that affect this workflow
- It is a snapshot, not a sync. Each refresh is a new export you run and commit. Flint does not watch Confluence, schedule exports or push to Git.
- Keep hand edits out of the exported folder. A refresh replaces the folder, so edits made there appear as reversions in the next diff. Fix content in Confluence instead.
- Moves change paths. Page-ID filenames survive renames, but moving a page under a different parent moves its file to a different directory. See how links and filenames behave across exports.
- Links to unselected pages stay in Confluence. Only links between exported pages become relative paths.
- Complex tables stay HTML. The merged-cell table in Architecture overview is HTML inside the Markdown. Check how your repository host or site generator displays it; the MkDocs guide shows one renderer where a link inside such a table needs attention.
- Repository access replaces Confluence permissions. Exported files do not keep page restrictions. Only commit pages that everyone with repository access may read.
- Collection limits still apply. A tree larger than 500 pages must be split; see exporting a large space in batches.
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.