FLINT MARKDOWN EXPORT · USE CASE
Turn exported Confluence Markdown into a documentation website
Use a Git documentation export as the source of a static documentation site, and test the parts that need attention.
Finished result
A local MkDocs site with the five handbook pages in a navigation menu, working page links and images, task-list checkboxes, and one known link to fix inside a merged-cell table.
Tested on 2026-11-03 with MkDocs 1.6.1, pymdown-extensions 12.3 and Python-Markdown 3.11.2, following the MkDocs configuration documentation. Flint does not install, configure or publish MkDocs; those steps belong to MkDocs and your hosting.
Part 1: export with Flint
- Export the handbook tree with the Git documentation preset, as in moving Confluence docs into Git. Page-ID paths keep the site’s addresses stable when titles change.
- Review the warnings. The sample’s Release checklist has a Jira issue list that is not exported.
- Download the ZIP. The sample is
ENG-1001-2026-11-03.zip.
Part 2: set up MkDocs
Arrange the project so the exported folder can be replaced on each refresh while your own files stay outside it:
mkdocs.yml your configuration
docs/
index.md your home page
handbook/ the extracted export (replace on refresh)
1001.md
1001/1002.md
1001/1002/1003.md
1001/1004.md
1001/1004.assets/system-overview.svg
1001/1005.md
all-pages.md
manifest.jsonmkdir -p docs
unzip -q ~/Downloads/ENG-1001-2026-11-03.zip -d docs
mv docs/1001 docs/handbookThe mkdocs.yml used for the test gives the pages readable titles in the menu, keeps the combined file and manifest out of the site, turns on task-list checkboxes and reports broken links:
site_name: Team documentation
nav:
- Home: index.md
- Engineering Handbook:
- Overview: handbook/1001.md
- Onboarding: handbook/1001/1002.md
- First week: handbook/1001/1002/1003.md
- Architecture overview: handbook/1001/1004.md
- Release checklist: handbook/1001/1005.md
exclude_docs: |
/handbook/all-pages.md
/handbook/manifest.json
markdown_extensions:
- pymdownx.tasklist
validation:
links:
not_found: warn
anchors: warn
unrecognized_links: warnBuild with strict checking, then preview locally. The test ran MkDocs through uv without a permanent install; with MkDocs and pymdown-extensions installed another way, run mkdocs build --strict and mkdocs serve directly.
uvx --from mkdocs --with pymdown-extensions mkdocs build --strict
uvx --from mkdocs --with pymdown-extensions mkdocs serveThe strict build finished without warnings, and mkdocs serve serves the preview at http://127.0.0.1:8000/.
What worked, and what needs attention
| Exported content | Result in MkDocs |
|---|---|
| YAML frontmatter | Read as page metadata and not shown on the page. Titles in the menu come from nav. |
| Relative Markdown links | Rewritten to page addresses, such as 1002/. Broken ones are reported by the strict build. |
Images in .assets folders | Displayed; the relative paths are adjusted for each page’s address. |
| Blockquote panels | Displayed as quotes with a bold label, such as Warning:. |
| Task lists | Checkboxes with pymdownx.tasklist; without it, [x] and [ ] appear as text. |
| Merged-cell HTML table | The table displays, but the link inside it keeps href="1002.md#before-day-one". MkDocs does not rewrite links in raw HTML, so it leads to a missing page, and the strict build does not report it. |
| Jira issue list | An HTML comment marker, not visible on the page. |
Find links inside HTML before you publish, from the project root: grep -rn 'href="[^"]*\.md' docs/handbook. Then either simplify the table in Confluence so it exports as a Markdown table, whose links MkDocs does rewrite, or accept that the link needs fixing after each export.
Refreshing the site
- Replace
docs/handbookwith each new export; keepmkdocs.ymlandindex.mdoutside it. - A new page that is not in
navstill builds; MkDocs mentions it in an informational message. Add it to the menu. - When a page moves in Confluence, its path changes and the old
naventry points to a missing file. The strict build stops with a warning until you updatenav. - Use export comparison to see added, moved and missing pages before you edit the menu.
Sample files
- ENG-1001-2026-11-03.zipThe Git documentation export used for the site.
- mkdocs.ymlThe MkDocs configuration from the test.
- index.mdThe home page placed outside the exported folder.
Limits
- Publishing the built site, access control and hosting are outside Flint. A public site exposes everything in the export; Confluence permissions do not carry over.
- Only MkDocs with the configuration above was tested. Themes, plugins and other site generators handle HTML tables, callouts and links differently.
- Page-ID addresses such as
/handbook/1001/1002/are stable but not descriptive. A title-based filename pattern gives readable addresses that change on rename.
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.