Opens in a new tab

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.

Markdown and MDX Frontmatter is read Import straight into a version

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.
In your ZIP
docs/
  getting-started/
    introduction.md
    quickstart.md
  core-concepts/
    authentication.md
    webhooks.mdx
In WP Super Docs
Getting started
Introduction
Quickstart
Core concepts
Authentication
Webhooks

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. 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. 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. 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. 4
    Review, fix images, publish Walk the navigation, move images into your media library, then publish.
Import Markdown ZIP upload
payments-api-docs.zip 2.4 MB
Payments API
v2.4

Import an older export into an older version to backfill history.

Overwrite existingUpdate docs whose slug already matches
64created
9categories
0skipped

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 fileBecomesIf missing
titleDocument titleFirst heading in the file
slug or idURL slugThe filename
descriptionExcerpt, used in search and related docsLeft empty
order or sidebar_positionPosition in the sidebarZero, so alphabetical by folder
sidebar_labelShort label in the navigationThe title is used
status or hidden or draftPublished or draft statePublished

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.

Save to list

This website uses cookies to enhance your browsing experience and ensure the site functions properly. By continuing to use this site, you acknowledge and accept our use of cookies.

Accept All Accept Required Only