atlassian-confluence-export-html-to-google-okf

Turns a Confluence space export HTMLs into a Google Open Knowledge Format v0.2 bundle: one markdown file per page, hierarchy preserved, attachments carried across, every internal link rewritten to a working relative path.

Built to be run either by hand or as a Claude Code skill. scripts/confluence_to_okf.py does the whole conversion and has no state outside its two arguments, so running it directly and invoking the skill produce identical output.

Requirements

Python 3 plus two libraries:

python -m pip install --user beautifulsoup4 markdownify

If either is missing the script exits with that exact install line rather than a traceback. Verified on Python 3.13.14, beautifulsoup4 4.15.0, markdownify 1.2.3.

Getting the input

Export the space from Confluence as HTML (not PDF, not XML) and unzip the result. The folder must contain:

index.html            Space Details table, plus a nested <ul> tree of every page
<Name>_<id>.html      one file per page; some come out as a bare <id>.html
attachments/<id>/...  per-page attachments
styles/               Confluence CSS, not carried into the bundle

No index.html means it is not a space export, and the script refuses to guess.

Export with an account that can read every page you care about. Pages the exporter cannot see are silently absent from the export while still being named in the tree, which is exactly what the Missing list below reports.

Usage

python scripts/confluence_to_okf.py "<source-export-folder>" "<target-bundle-folder>"

Both arguments are positional and required. The only flag is --force, explained below. The target must not be inside the source.

[!warning] Every run is a full rebuild, and the target is deleted first This is deliberate: a stale bundle gets replaced wholesale rather than half-merged with fresh output. Two guards keep that from being a foot-gun. The target is wiped only if it is empty or already carries an okf_version root index.md, meaning it is a bundle this tool made. Anything else aborts with the target untouched.

--force removes that check and destroys whatever is in the target. Read the path twice before using it.

Because a rebuild is total, any file you hand-add inside the bundle is lost on the next run. Keep edits outside the bundle, or re-apply them from a script.

What comes out

<target>/index.md                     bundle root listing; frontmatter is okf_version only
<target>/<space>.md                   the root page's own content
<target>/<slug>.md                    one concept doc per Confluence page
<target>/<slug>/index.md              directory listing, for every page that has children
<target>/unfiled/                     pages absent from the tree
<target>/references/attachments/      attachments, copied verbatim

The page tree in index.html is the sole authority for hierarchy. A page with children becomes <slug>.md plus a <slug>/ folder holding them; a childless page is just <slug>.md. Titles are slugified, characters illegal in Windows filenames are replaced, and collisions get a -2 suffix.

The root page is the one exception. A Confluence export always has a single root page named after the space, so its children sit directly in the bundle root rather than under a <space>/ folder that would only repeat the bundle folder's own name one level down. The bundle root index.md is its listing, which makes it the only parent with no directory index of its own.

Each concept doc carries OKF frontmatter: type: Confluence Page, the real title, the space name as its one tag, a resource URL pointing back at the live page, and a sources entry naming the source HTML file plus its author and last-modified date. That last part is the provenance trail: every generated file says which export file it came from.

Design decisions worth knowing

Three choices will look wrong until you know why. OKF-FORMAT.md covers all of them plus the full OKF v0.2 field reference.

Links are relative, not /-absolute. OKF permits both. Relative wins because it keeps the bundle portable: it can be moved, renamed, or nested inside a larger vault and the links still resolve. A /-absolute link only works for a consumer that already knows where the bundle root is, and Obsidian reads a leading / as vault root, which breaks every link the moment the bundle is not at the top.

Link targets are percent-encoded, but real anchors are not. A page titled C# becomes C%23.md in link targets; left literal, that # reads as a fragment marker and the link dies. A genuine anchor is the mirror case: Page.html#2.3-Jira-Projects keeps its # literal, appended after the path is encoded.

?query tails are dropped, #fragment tails are kept. Confluence appends a render hint to image sources (attachments/1/2.png?width=816) that matches no file on disk and has nowhere to go in markdown image syntax. A fragment is a real anchor and survives.

Confluence's own site-absolute links (/wiki/display/...) name pages on the live server rather than files in the export, so they pass through untouched by design.

Files in this skill

File	Audience
README.md	you, right now
SKILL.md	Claude Code: how to run the script and reconcile its report
OKF-FORMAT.md	the OKF v0.2 spec, the full Confluence-to-OKF mapping table, and every deliberate deviation
scripts/confluence_to_okf.py	the entire conversion

The mapping lives in the script and nowhere else, so it stays the one place that changes when the mapping has to change. Change it and update the mapping table in OKF-FORMAT.md to match.

Installing as a Claude Code skill

Drop the folder into your skills directory:

cd ~/.claude/skills && unzip atlassian-confluence-export-html-to-google-okf.zip

Then invoke it by name, naming both folders:

/atlassian-confluence-export-html-to-google-okf convert <source> to <target>