Migrate from GitBook to Arkiv Knowledge

This guide explains the fastest path to move existing GitBook docs into this app with minimal manual cleanup.

1) Export content from GitBook

• Export in Markdown when available (best fidelity).
• Download media files from .gitbook/assets.
• Keep source files in version control so migration can be repeated.

2) Normalize GitBook syntax

Use the built-in converter at /migrate/gitbook.

It automatically converts common GitBook-specific syntax, including:

• frontmatter description blocks
• {% hint %} callouts
• <figure> and <picture> image blocks
• {% embed %} blocks
• {% code %} wrappers
• {% stepper %} and {% step %} blocks
• heading anchor tags like ``

For batch migration in local scripts, use:

• pnpm migrate:gitbook -- <input.md> [output.md] --summary

3) Create or update pages in Arkiv

1. Open your target space.
2. Create a page (or edit an existing page).
3. Paste normalized markdown.
4. Save as published.

4) Validate links and assets

• Verify internal links resolve to existing page slugs.
• Ensure images point to reachable URLs or hosted assets in this app.
• Confirm headings, callouts, and lists render correctly in Preview.

5) Keep migration repeatable

• Keep source markdown in a migration folder.
• Re-run conversion after upstream edits.
• Track changes as normal page revisions in Arkiv.

Troubleshooting

• If GitBook tags still appear, run the converter again and check the transform summary.
• If images do not render, fix asset paths first.
• If a page slug already exists, edit the canonical page instead of creating a duplicate.