If you have docs somewhere else, you can move them. Most platforms either store docs as MDX (easy migration) or have an export option (only slightly harder).
This page covers the common sources. If yours isn't listed, the general approach at the bottom applies.
From Mintlify#
Mintlify already stores pages as MDX. The migration is mostly a copy-paste with a few component name swaps.
Clone your Mintlify repo
git clone https://github.com/your-org/your-mintlify-docs.git
cd your-mintlify-docsMap components
Mintlify and Dokly share most component names — <Card>, <CardGroup>, <Steps>, <Tabs>, <Note>, <Warning>. Where they differ:
| Mintlify | Dokly |
|---|---|
<Note> | <Callout type="note"> |
<Warning> | <Callout type="warning"> |
<Tip> | <Callout type="tip"> |
<Info> | <Callout type="info"> |
<CodeGroup> | <Tabs> |
<Frame> | (just ![]() — Dokly auto-frames images) |
A simple find-replace handles most of these.
Adjust frontmatter
Mintlify uses title and description — same as Dokly. Add a slug to each file matching the file path (e.g., editor/writing.mdx → slug: editor/writing).
Mintlify-specific fields like mode: wide, sidebarTitle, and iconType map cleanly:
sidebarTitle→ same namemode: wide→ not yet supported (pages are responsive by default)iconon a card → same name
Import into Dokly
For now, copy-paste each MDX file into a new page in the editor (the slash menu's /import action will paste the MDX correctly). A bulk importer is on the roadmap.
Verify
Open each migrated page on the live site. The components should render identically. If something looks off, switch to source view and compare.
From GitBook#
GitBook supports MDX export but stores pages in a proprietary tree structure. Use the export option:
Export your GitBook space
Settings → Export → Markdown. You'll get a zip of .md files mirroring your sidebar tree.
Convert to MDX
GitBook exports .md, not .mdx. Most files will parse as MDX without changes. The exceptions:
- GitBook hint blocks (
{% hint style="info" %}) need to become<Callout type="info">. - GitBook tabs (
{% tabs %}) need to become<Tabs>. - GitBook code groups (
{% code-group %}) need to become<Tabs>.
A small script can do this. We have a community-maintained one at github.com/dokly/migrators.
Set frontmatter
GitBook exports don't include slugs. Generate one per file based on its path and add it to each frontmatter block.
Import into Dokly
Same as Mintlify — copy-paste each file into a new page.
From Docusaurus#
Docusaurus pages are MDX in a docs/ folder. The structure is closer to Dokly than GitBook.
Identify your docs folder
Usually docs/ at the repo root. Each .md or .mdx file is a page.
Map components
| Docusaurus | Dokly |
|---|---|
:::tip ... ::: (admonition) | <Callout type="tip"> |
:::warning ... ::: | <Callout type="warning"> |
<Tabs> (with <TabItem>) | <Tabs> (with <TabsContent>) |
| MDX imports of custom components | Not supported — convert to standard components |
Migrate Docusaurus-specific frontmatter
Docusaurus's sidebar_position becomes Dokly's order. sidebar_label becomes sidebarTitle. slug works the same way.
Drop the imports
Docusaurus pages often have import Tabs from "@theme/Tabs" at the top. Delete those — Dokly's components are globally available.
From ReadMe#
ReadMe doesn't expose Markdown directly — pages are stored in a proprietary editor. Two options:
- Manual rewrite. For small docs (< 30 pages), the fastest path is to read each ReadMe page and rewrite it in Dokly. You'll improve a lot of pages along the way.
- HTML scrape + cleanup. For larger docs, scrape the rendered HTML and convert to Markdown with a tool like Pandoc. Plan for significant cleanup — automated conversion produces ugly Markdown.
ReadMe's Recipes don't have a direct equivalent — convert them to a <Steps> component with embedded code blocks.
From Notion#
Notion exports as Markdown via Workspace Settings → Export. The output is messy — Notion blocks don't always map cleanly.
For Notion, the realistic path is:
- Export to Markdown.
- Use the Markdown as a raw source you'll edit heavily.
- Generate the structure with
/generatein Dokly using the exported text as the brief.
You'll spend less time on a half-broken automated conversion than on a clean rewrite.
General approach#
For any source not listed:
- Get your content out as Markdown or HTML (one file per page).
- Convert HTML to Markdown if needed (Pandoc, Turndown).
- Split into one file per Dokly page.
- Add frontmatter to each (
title,slug,description,parent,order). - Replace any custom components with Dokly equivalents.
- Paste each page into the editor.
For 50+ page migrations, talk to us — we can sometimes provide a one-off importer or do the migration as a paid service.
After migration#
Run through the SEO checklist to make sure:
- Slugs match the URL patterns from your old site (preserves SEO rankings).
- Set up redirects from old paths to new paths if slugs changed.
- Submit the new sitemap to Google Search Console.
- Update any external links pointing at the old docs.