Migrate Existing Documentation

Move Markdown and MDX into Publier, translate components, and verify URLs before switching your host.

Move content into a fresh Publier project, qualify a preview deployment, then switch traffic. Publier does not automatically import another platform’s configuration or components. For Mintlify, also use the Mintlify mapping guide.

1. Inventory the live site

Reconcile your repository, sitemap, navigation, and deployed site. List every public page, including unlinked pages, downloads, older versions, and important fragment links. Record private pages and the host controls that protect them.

Keep a migration table in your project:

Count pages and assets, then reconcile those counts against the new build. Keep the old deployment as your rollback target until the new site passes qualification.

2. Create a clean destination

Complete installation, then scaffold separately:

publier new migrated-docs --template docs
cd migrated-docs
corepack pnpm install
publier login

Retain the scaffold’s Astro configuration, content collections, package manifest, and workspace settings. They establish the integrations, loaders, and dependency graph. Development and builds require a Publier seat.

3. Move pages and assets

With the default loader and route, content paths determine destinations:

src/content/docs/quickstart.mdx       → /docs/quickstart
src/content/docs/reference/index.mdx  → /docs/reference
src/content/docs/reference/auth.mdx   → /docs/reference/auth
public/images/setup.png              → /images/setup.png

Give each page an explicit title and useful description:

---
title: Quickstart
description: Install the client and make your first request.
sidebar:
  order: 1
---

## Install the client

Your product's installation instructions go here.

Copy assets into public/, preserving paths when possible. Rewrite page links to their final destinations and check relative images from nested pages. Reconcile files that would produce the same URL before building.

4. Translate framework features

Review MDX imports, JSX components, frontmatter, code-fence options, snippets, and plugins against Publier’s contracts:

• Replace vendor components with Publier components or standard Markdown.
• Reimplement custom interactive UI with Astro or Qwik; copied React islands do not run as Publier components.
• Recreate navigation, section metadata, and page ordering.
• Move shared fragments through the snippet workflow.
• Generate API pages through the OpenAPI workflow.

Convert one representative page first, including code, an image, a callout, tabs, and a cross-link. Inspect it before converting the remaining pages.

5. Preserve destinations

Keep existing URLs where the new route layout permits. Configure redirects for moved pages at your host; verify HTTP status, Location, and any required query-string preservation. Fragments are browser-controlled, so check destination heading IDs separately.

Astro supports a redirects map, but an unadapted static build emits HTML redirect pages. This does not establish an HTTP 301 or 308 at your host. Follow Astro’s redirect documentation and your provider’s contract.

Point internal links directly to new destinations; retain old redirects for external bookmarks and search results.

6. Qualify the new build

corepack pnpm run build
corepack pnpm run preview

Check the built preview, including search; development alone does not qualify the production index.

1. Reconcile every inventory destination with a page, redirect, or intentional retirement.
2. Check images, downloads, code, callouts, and every tab panel.
3. Exercise desktop/mobile navigation and active-page state.
4. Search for distinctive migrated text and follow its result.
5. Check titles, descriptions, canonical URLs, sitemap, and enabled AI artifacts.

Follow deployment for credentials and hosting. Set the production origin before building. Test host redirects, headers, and reader access controls on the deployed preview. Sidebar hiding and indexing exclusions do not protect private content.

7. Switch and verify

Publish the qualified artifact and switch your domain or routing. Repeat checks over public HTTPS, including bookmarked old URLs. Restore the old host release if a critical check fails, preserving the failed candidate for diagnosis.

Continue with upgrades and rollbacks and content maintenance.