Docsheaf
Sign inStart for free
Switch to Docsheaf

Bring your docs with you

Import the Markdown you already have — GitBook syntax included — page by page in the app, or all at once through the REST API.

Start for freeGet migration help

Where are you coming from?

Docsheaf imports Markdown. Here’s how to get it out of the tool you use today, and what to expect.

GitBook

Take the Markdown from your Git Sync repository. {% hint %}, {% tabs %}, {% stepper %}, {% code %}, {% embed %} and <details> import as real blocks.

Docusaurus, MkDocs and plain Markdown

Standard Markdown imports cleanly, front matter included. MDX components and admonitions like :::note or !!! note arrive as text — turn them into hints after import.

Notion

Export your pages as Markdown, then import them. Databases don’t carry over as tables, and images exported as local files need to be uploaded again.

Confluence

Confluence has no Markdown export. Convert its HTML or Word export with a tool such as Pandoc, then import — expect to tidy macros and layouts by hand.

How it works

Four steps from export to published

  1. 1

    Create a site and a space

    Every space belongs to a docs site. Start with one space for your existing docs; add more sections later.

  2. 2

    Import your pages

    Use Import Markdown in the page tree to paste text or choose a .md file, or script a bulk import with the API.

  3. 3

    Review in a change request

    Import into a change request to check the result on a diff before anything reaches your main branch.

  4. 4

    Publish

    Pick your colors and logo, connect a custom domain, and publish. Search, llms.txt and a sitemap come with it.

What converts

Markdown in, real blocks out

The importer understands GitHub-flavoured Markdown and GitBook’s Liquid-style tags.

In your MarkdownIn Docsheaf
Front matter title and descriptionPage title and description
A leading # HeadingThe page title
HeadingsHeadings (levels below H3 become H3)
Bulleted, numbered and - [ ] task listsLists and task lists
``` code fencesCode blocks with their language
{% code title="…" %}Code blocks with a title
TablesTables
> quotes and ---Quotes and dividers
{% hint style="…" %}Hints: info, success, warning, danger
{% tabs %} / {% tab %}Tabs
{% stepper %} / {% step %}Steppers
{% embed url="…" %}Embeds
<details><summary>Expandable sections
Images at a public URLImage blocks

What needs a hand

Know before you start

A few things don’t convert automatically yet.

  • Page order from SUMMARY.md — recreate the tree, or script it with the API
  • MDX components and other tools’ admonition syntax
  • Images stored alongside your files — upload them again
  • GitBook blocks Docsheaf doesn’t have yet: cards, columns, math, OpenAPI and reusable content
  • Notion databases and Confluence macros

Bulk import

Script it with the REST API

The same endpoint the app uses. Point it at a change request branch to review the import before merging.

One call per page

POST the Markdown to /spaces/{spaceId}/content/import. A leading H1 or front matter title names the page.

Review first

Use /spaces/{spaceId}/change-requests/{number}/content/import to import into a change request instead of main.

Keep the structure

Create groups with POST /content/pages, then pass their id as parentId when you import.

API overview
import.sh
# Import every Markdown file in ./docs as a page of one space.
# Needs curl and jq. Create a token under Account settings → API tokens.
DOCSHEAF=https://<your-docsheaf-host>/api/v1
TOKEN=dsk_...
SPACE=spc_...

for file in docs/*.md; do
  jq -Rs '{markdown: .}' "$file" |
    curl -sS -X POST "$DOCSHEAF/spaces/$SPACE/content/import" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      --data-binary @-
done

No lock-in, in either direction

The formats you bring in are the formats you can take out.

Markdown for every page

Fetch any page as Markdown through the API, or add .md to a published page’s URL.

Whole-site export

llms-full.txt holds the content of an entire published site in one Markdown file.

Open API

Every page, tree and revision is available over the documented REST API.

For developers

Frequently asked questions

Will my GitBook pages import without changes?

Most will. Docsheaf reads GitBook’s Markdown dialect — hints, tabs, steppers, titled code blocks, embeds and expandables. Blocks Docsheaf doesn’t have yet, such as cards, columns, math or OpenAPI blocks, need adjusting after import.

Does import keep my page hierarchy?

Each import creates one page. Recreate your groups in the page tree, or script the whole structure with the REST API: create groups first, then import each file with its parentId. SUMMARY.md files aren’t read yet.

What happens to my images?

Images that live at a public URL are kept. Images stored next to your Markdown files — for example in .gitbook/assets — have to be uploaded to Docsheaf again.

Can I review an import before it goes live?

Yes. The import endpoint works on change request branches too, so you can import into a change request, review the diff, and merge when it looks right.

Can I get my content back out?

Always. Every page is available as Markdown through the API and on your published site, and llms-full.txt exports a whole site as one file.

Moving a large docs site?

Tell us where your docs live today and how big they are. We’ll help you plan the move.

Get migration helpStart for free