---
title: "Migration overview"
url: "/help/buuk/migration-overview"
updated: "2026-10-22T11:13:40.020Z"
---
# Migration overview

You do not have to rebuild your help center by hand. Buuk imports existing documentation, converts it into editor blocks, and lands every page as a draft you review before anything goes live.

Pick the path that matches what you have today. The articles in this folder cover all three in order.

## Choose a path

- A folder of `.md` or `.mdx` files exported from another tool — see [Import markdown](./import-markdown).
- A live docs site at a public URL — see [Import from a live docs site](./import-from-live-site).
- Content already in Buuk that you need as files — see [Export your docs](./export-your-docs).

| You have | Use | Result |
| --- | --- | --- |
| Markdown folders or another help center's file export | Markdown import | One draft per file, with folders mapped to sections |
| A docs site running at a URL | Website import | One draft per page the crawler finds |
| Published articles you are leaving with | CLI export | Markdown and OpenAPI files, ready to commit |

## What maps cleanly

The import pipeline turns plain markdown into editor blocks. These survive the trip without a rewrite:

- Folders and URL paths. On a markdown import, folder structure becomes sections. On a website import, the first path segment of each URL becomes the section.
- Headings, bullet and numbered lists, bold, italic, links, and blockquotes keep their formatting.
- Fenced code keeps its language when the fence names one.
- GitHub-style tables and callouts such as `> [!NOTE]` become editor blocks. `INFO` maps to note and `CAUTION` to warning.
- Dividers (`---`) keep their place in the page.

> [!NOTE]
> Imports never publish. Every page lands as a draft, and re-importing the same source updates matched drafts in place instead of creating duplicates.

## What needs a manual pass

Most content moves as-is, but a few things genuinely need attention after import:

- Headings deeper than H3 flatten — `####` reads as an H3 in the editor.
- Nested lists flatten to one level. If the nesting carries meaning, split it into H3 sections.
- A fenced block with no language is filed as JavaScript. Tag your fences so snippets keep the right highlighting.
- Images carry over with their original URLs — files are not rehosted. If the old site will go dark, re-upload the images in the pages that matter.
- Component-only markup from another tool — tabs, embeds, custom widget syntax — arrives as plain text or is dropped, and each drop is listed in the import report.

## Migration checklist

1. **Inventory**
   Count the pages you are moving and decide the path: markdown import, website import, or both.

2. **Spot-check**
   Import two or three representative files or pages first. Check slugs, sections, code, tables, and callouts before you commit to the full run.

3. **Import everything**
   Run the full import. Pages land as drafts, organized into sections.

4. **Review and publish**
   Fix slugs and section placement, run a manual pass over the pages flagged above, and publish each section when it reads right.

## Related

- [Import markdown](./import-markdown)
- [Import from a live docs site](./import-from-live-site)
- [Export your docs](./export-your-docs)
- [Organize sections and folders](./organize-sections-and-folders)
- [Publish your help center](./publish-your-help-center)