BlueConfetti

FLINT MARKDOWN EXPORT · CHECK

Check a Markdown export before treating it as a dependable snapshot

Confirm an export contains what you meant to keep before you file it as the copy of record.

Finished result

A short record showing that four of five intended pages were exported, that one could not be read, and that the snapshot was not accepted until it is exported again.

Example: one page missing

A maintainer means to keep all five handbook pages (1001 to 1005). When the export runs, Release checklist (1005) cannot be read, so the summary names it as a page that could not be read and it is not in the ZIP. It is easy to miss in a quick glance at the files, which is why the checks below start from the manifest.

Run the checks

Run these from the export’s top folder. They were tested with jq 1.7.1 in zsh and bash.

  1. Count the pages. jq '.pages | length' manifest.json prints 4.
  2. Compare with what you intended. List the page IDs you meant to export and compare:
comm -23 <(printf '%s\n' 1001 1002 1003 1004 1005 | sort) <(jq -r '.pages[].page_id' manifest.json | sort)

The output, 1005, is the intended page that is not in the export.

  1. Read the skipped and limits lists. jq -c '.skipped[]' manifest.json explains the gap:
{"id":"1005","title":"Release checklist","type":"page","reason":"could not be read"}

jq -c '.limits[]' manifest.json lists files left out for size; here it prints nothing.

  1. Read page warnings. jq -r '.pages[] | select(.warnings | length > 0) | "\(.title): \(.warnings | join("; "))"' manifest.json prints any conversion warnings by page. Read what each warning means.
  2. Check that listed files exist.
jq -r '.pages[].assets[]' manifest.json | while read -r f; do test -f "$f" && echo "ok $f" || echo "missing $f"; done
ok engineering-handbook/architecture-overview.assets/system-overview.svg
  1. Find links that still open Confluence. Search for your site address, for example grep -rn '](https://example.atlassian.net/wiki/' --include='*.md' .. These lead to unselected pages and need Confluence access.
  2. Open representative files in the tool you will use: one with images, one with a table, one deep in the hierarchy. Follow a few links.
  3. Look for permission-sensitive content. The export contains what the exporting person could read. Check nothing is included that the snapshot’s readers should not see.

Record the snapshot

Write down what you checked, next to the ZIP. Useful facts from manifest.json are exported, site, root_page_id, scope and options. Its generator value identifies the export format, not the Marketplace version. The record below was written for this guide; Flint does not create it.

Sample files

A snapshot is not a backup

A Markdown export is a readable copy of page content, not a way to restore Confluence. Flint does not import files back into Confluence. The export does not contain page history, comments or page restrictions. Some macros become markers, attachments are subject to size limits, and whiteboards and databases are skipped. Use your site’s own backup arrangements for recovery, and keep snapshots for reading, review and handoff.

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.