Migrate / GitBook
Move your GitBook space to WordPress.
Export your space as Markdown, upload the ZIP, and your folder structure becomes your navigation. The docs end up in your own database, on your own domain, with no monthly bill for hosting them.
Why people move
Three reasons this comes up
GitBook is a capable documentation platform. The people who leave it are usually not unhappy with the editor.
You already pay for WordPress
If your marketing site runs on WordPress anyway, documentation on a separate platform means two bills, two logins, and content in two places.
SEO on your own domain
Docs at your own address build authority for your domain rather than a subdomain you do not control, and they sit alongside your existing SEO setup.
You want the content back
Docs become a regular post type in your database. They back up with everything else and keep working the day you stop paying anyone.
Structure
Your folders become your navigation
The importer walks the archive. Every sub folder becomes a category, every Markdown file inside becomes a doc, and the whole thing lands under the product you choose.
- MDX is handled too. JSX components are stripped out rather than dumped into your content as raw text.
- Frontmatter is read. Title, slug, description, and order are picked up when they are there.
- Sensible fallbacks. No frontmatter? The filename becomes the slug and the first heading becomes the title.
getting-started/
introduction.md
quickstart.md
core-concepts/
authentication.md
webhooks.mdx
Sub folders become categories, files become docs.
The process
Four steps, about twenty minutes
Nothing is published until you say so, and a failed first attempt costs nothing but the time. Delete the imported docs and try again with a different structure.
-
1
Get your content out as Markdown You need a ZIP of md files with the folders intact. GitBook export options vary by plan, so check what yours offers.
-
2
Check the folder structure This becomes your navigation, so it is worth two minutes before you upload. Rename anything you would not want as a category.
-
3
Upload the ZIP Pick the product it lands under, and optionally a version. Importing an older export straight into v1 is the fastest way to backfill version history.
-
4
Review, fix images, publish Walk the navigation, move images into your media library, then publish.
Import an older export into an older version to backfill history.
Nine folders became nine categories in one pass.
Frontmatter
What gets read from your files
If your pages carry YAML frontmatter, these keys are picked up. Anything missing falls back to something sensible, so a plain Markdown file with no frontmatter still imports cleanly.
| Key in your file | Becomes | If missing |
|---|---|---|
| title | Document title | First heading in the file |
| slug or id | URL slug | The filename |
| description | Excerpt, used in search and related docs | Left empty |
| order or sidebar_position | Position in the sidebar | Zero, so alphabetical by folder |
| sidebar_label | Short label in the navigation | The title is used |
| status or hidden or draft | Published or draft state | Published |
That last row is the one to read twice. A GitBook export usually carries none of those three keys, which means every page arrives published.
Before you commit
What lands cleanly, and what needs an hour
Nobody enjoys finding this out after cancelling their old subscription, so here it is first.
Comes across automatically
- Page titles and body content
- Folder structure, as categories
- Code blocks with their language intact
- Internal links between pages
- Frontmatter metadata where it exists
- MDX files, with JSX components stripped
Plan an hour for these
- SUMMARY.md is not read. GitBook uses it to define sidebar order. The importer orders by folder and frontmatter instead, so hand arranged navigation needs redoing.
- Everything arrives published. Without a status, hidden, or draft key in the frontmatter, pages default to published. Import into a product you have not linked yet.
- Images are not rehosted. Content keeps pointing at GitBook URLs. Move them into your media library before you close the account.
- Redirects are not created. Set up 301s from your old URLs if the docs ranked.
- GitBook specific blocks. Hints, tabs, and embeds may need converting to the equivalent shortcodes.
Questions
Before you start
Can I import more than one space?
Yes. Run the importer once per space and point each at its own product. Each gets its own navigation, search scope, and URL space.
What happens to my versions?
Version history is not reconstructed on its own, but you can rebuild it. Import each old export into its own version, newest last, and the switcher fills in.
Will it overwrite anything?
Only if you tell it to. With overwrite off, docs whose slug already exists are counted as skipped and left alone. The source ZIP is only ever read.
How big a ZIP can I upload?
Whatever your server upload limit allows. For a very large space, split the export by top level folder and run the importer more than once.
What if it does not come across cleanly?
Delete the imported docs and try again with a different folder structure. Nothing in GitBook is touched, so a failed attempt costs you nothing.
Can I try before I buy?
Zip up a few pages and send them over. We will tell you what will and will not survive the trip before you spend anything.
Next step
Send us a sample export.
Zip up a few pages and we will tell you what survives the trip, before you spend anything. There is a 14 day money back guarantee behind the purchase.
GitBook is a trademark of GitBook Inc. and is not affiliated with Nahnu Plugins. Export options described here reflect publicly available information at the time of writing, and import behaviour reflects WP Super Docs version 1.5.75.