Local guide · 31 October 2026

BrokkrWiki 0.1.2

Inspect a Confluence HTML export, review what may be lost, map pages into BookStack, then verify and retain a rollback record.

This guide describes the purchased local wheel and the fictional practice export. The separately downloadable free guide pack contains static practice material but no application or wheel.

BrokkrWiki local mapping editor showing five pages needing review from the fictional 21-page sample — Actual Chrome capture of BrokkrWiki 0.1.2 on Linux. The synthetic 21-page sample is filtered to five pages needing review; warning reasons sit beside destination choices. This is an offline prediction, not a completed migration.

Install the local edition

Extract the complete buyer ZIP and open a terminal inside BrokkrWiki-0.1.2. Python 3.10+ and internet access for pip dependency installation are required. BookStack and Confluence are not bundled.

python3 -m venv ../brokkrwiki-venv
../brokkrwiki-venv/bin/python -m pip install ./brokkrwiki-0.1.2-py3-none-any.whl
../brokkrwiki-venv/bin/brokkrwiki --version

Expect BrokkrWiki 0.1.2. See INSTALL.md for Windows paths and checksum verification. In the commands below, brokkrwiki means that virtual environment's executable.

Before an actual migration

Use your own disposable staging BookStack and a Confluence HTML space export. Read the source pages, review the predicted losses, and back up the target. The offline report needs no BookStack URL or token.

Try the fictional example

Analyze. Run brokkrwiki analyze samples/confluence-sample-export.zip --out readiness and open readiness/readiness.html. The sample has 21 fictional pages; 20 are planned to migrate and five need review.
Plan and preview. Run brokkrwiki plan samples/confluence-sample-export.zip --out mapping.json, then brokkrwiki preview samples/confluence-sample-export.zip --mapping mapping.json. Preview lists operations without contacting BookStack.
Use the local UI. Run brokkrwiki serve --port 8765 --workdir brokkr-workspace and open http://127.0.0.1:8765/. Choose Try the synthetic sample export. In Readiness, use Review mapping beside a warning to reach that page's mapping controls.
Review and save. Needs review shows only warned pages while preserving all 21 mapping records when saved. Check each reason against the source export. Choose whether to migrate, exclude, rename, or change the BookStack target. Do not set an existing ID unless it matches the intended container.

BrokkrWiki narrow-screen mapping card showing a page warning, migrate control, BookStack target and name — The same synthetic mapping in a 390 px Chrome viewport. Page and container controls become cards; the visible filter does not remove hidden mapping decisions.

Move to a staging BookStack

After inspecting your own export, run migration only against a staging BookStack you control. Supply the API token through the CLI's hidden prompt or the local UI; never put it in command arguments, mappings or support messages. The local sandbox is an in-memory imitation, not a real BookStack.

brokkrwiki migrate export.zip --mapping mapping.json --url https://YOUR-STAGING-BOOKSTACK
brokkrwiki verify export.zip --mapping mapping.json --url https://YOUR-STAGING-BOOKSTACK --deep
brokkrwiki rollback --state mapping.state.sqlite --url https://YOUR-STAGING-BOOKSTACK --dry-run

Inspect page rendering, links, attachments, verification output and rollback preview. Keep mapping.json and mapping.state.sqlite. Applying rollback without --dry-run changes objects tracked as created by the migration; edited pages are preserved unless explicitly overridden.

Limits to plan around

Confluence HTML space export ZIPs are supported; XML, PDF, Word and REST exports are not. BookStack is the target; Wiki.js is not available.
Unknown or dynamic macros become review notes. History, comments, permissions, users, labels, blog posts and live macro behavior are not migrated. Some layouts and embeds are approximated, so the result is not pixel-identical.
The exact 0.1.2 wheel passed authentic Data Center 10.2.18, Cloud 2026 and Server 2016 HTML export regression against disposable BookStack 26.09.1, including deep verification, repeat migration and rollback. Data Center had one warned page and one source link unresolved during migration; deep verification found zero broken links. See SUPPORTED-EXPORTS.md for scope. Other versions, customer spaces and thousands-of-pages performance remain unverified.
Linux Chrome local UI checks use the fictional sample. Windows/macOS instructions are provided without host acceptance. Always rehearse your own export on staging.

The screenshots and example are synthetic. Warning labels predict conversion losses from the export; they do not replace source inspection or final BookStack review.