Migrate from Mintlify

Translate Mintlify navigation, frontmatter, and MDX components through a manual Publier migration.

Use your Mintlify repository as the source and a fresh Publier scaffold as the destination. Follow migration for inventory, redirects, previews, and cutover. There is no publier import command or automatic docs.json converter.

Configuration mapping

Mintlify’s docs.json navigation lists groups and pages. Publier’s default sidebar follows content directories, with metadata controlling labels and order.

Mintlify input	Publier destination
`name`, `description`	`site.name`, `site.description` in `publier.config.yaml`
Branding, colors, favicon	`theme.yaml`, `site.logo`, `site.favicon`, assets in `public/`
Navigation `groups` and `pages`	Content directories, section metadata, page `sidebar.order`
Tabs	`nav.docs.tabs`; `docs.tabSections` for separate folder sidebars
Products and versions	`nav.docs.products` with published destinations
External links	`nav.docs.links` or sidebar anchors
Redirects, domain, reader authentication	Your hosting configuration
OpenAPI navigation	Explicit API generation

Selectors link to published content; they do not translate pages or copy branches. See versioning.

For a group containing quickstart and authentication, create those pages under src/content/docs/get-started/, then configure:

site:
  name: Example Docs
  description: Guides and API reference for Example.
  url: https://docs.example.com
nav:
  docs:
    title: Example Docs
    tabs:
      - { label: Documentation, href: /docs }
      - { label: API reference, href: /docs/api }
docs:
  sidebar:
    meta:
      get-started: { label: Get started, order: 1 }

Publish a landing page at each tab destination. Give the two pages sidebar.order: 1 and sidebar.order: 2. They become /docs/get-started/quickstart and /docs/get-started/authentication; redirect different old URLs.

Frontmatter mapping

Mintlify can infer titles from filenames. Publier requires title. Compare Mintlify page metadata with these equivalents:

Mintlify field	Publier treatment
`title`, `description`	Keep the text; supply an explicit title
`sidebarTitle`	`sidebar.label`
Position in navigation	`sidebar.order`
`hidden`	`sidebar.hidden` affects navigation; review indexing separately
`tag`	`sidebar.badge`, using Publier’s badge format
`openapi`, `api`	Rebuild through the API generation workflow
`groups`	Enforce reader permissions at your host
`searchable`, `boost`, `contextual`	No direct field mapping; review search/UI needs

Mintlify’s hidden-page and indexing behavior does not transfer from a copied field. A sidebar-hidden Publier page remains reachable. Keep private pages outside the public build and establish host access controls before publishing them.

---
title: Quickstart
description: Make your first request with Example.
sidebar:
  label: Start here
  order: 1
---

Your migrated Markdown goes here.

Translate components explicitly

Familiar names can accept different children and props. Use explicit Publier imports and check the linked contracts:

Mintlify pattern	Publier pattern
`Note`, `Tip`, `Warning`	Callouts: `:::note`, `:::tip`, `:::caution`
`Steps` with `Step` children	Steps with `li` children
`Tabs` with `Tab title="…"`	Tabs with `labels` and named slots
`AccordionGroup`, `Accordion`	Accordion and AccordionItem from `@publier/primitives`
Linked `Card` in `CardGroup`	LinkCard in CardGrid
Imported snippet	Snippet with its configured directory

Replace Mintlify’s step children with semantic list items:

import { Steps } from '@publier/shell/components';

<Steps>
  <li><strong>Install the client.</strong> Follow your product's installation command.</li>
  <li><strong>Make a request.</strong> Run your first API example.</li>
</Steps>

Replace titled tab children with named slots:

import { Tabs } from '@publier/shell/components';

<Tabs labels={['Linux', 'Other platforms']}>
  <div slot="tab-0"><p>Your product's Linux instructions.</p></div>
  <div slot="tab-1"><p>Your product's other supported platforms.</p></div>
</Tabs>

Use an explicit syncKey to synchronize Publier groups. Review defaults instead of copying Mintlify’s sync or defaultTabIndex props. See the official Mintlify Steps and Tabs references.

Replace hosted workflows deliberately

Publier builds a site you deploy. Follow deployment for CI and hosting. Mintlify’s hosted assistant, agent, editor, and reader authentication do not become services in a Publier scaffold. Choose and qualify any separate backend or reader gateway your team needs.

For discoverability, use built Pagefind search and supported AI outputs. Finish by qualifying every old destination and component through the migration checks.