BlueConfetti

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

  1. 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.
  2. Review the warnings. The sample’s Release checklist has a Jira issue list that is not exported.
  3. 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.json
mkdir -p docs
unzip -q ~/Downloads/ENG-1001-2026-11-03.zip -d docs
mv docs/1001 docs/handbook

The 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: warn

Build 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 serve

The 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 contentResult in MkDocs
YAML frontmatterRead as page metadata and not shown on the page. Titles in the menu come from nav.
Relative Markdown linksRewritten to page addresses, such as 1002/. Broken ones are reported by the strict build.
Images in .assets foldersDisplayed; the relative paths are adjusted for each page’s address.
Blockquote panelsDisplayed as quotes with a bold label, such as Warning:.
Task listsCheckboxes with pymdownx.tasklist; without it, [x] and [ ] appear as text.
Merged-cell HTML tableThe 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 listAn 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

Sample files

Limits

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.