Migrations

Migrating from Mintlify

Bring an existing Mintlify docs.json and content tree into Shiso.

Shiso reads the same docs.json shape as Mintlify. Most sites can move over by pointing Shiso at their existing config and markdown files, then adjusting for the subset of features Shiso implements today.

What carries over as-is#

Navigation: tabs, groups, pages, nested groups, page objects (title / label, icon, tag, hidden), external links, anchors
Branding: name, description, logo, favicon, colors
Chrome: navbar, footer, banner
Appearance: appearance, fonts, styling.eyebrows, background
SEO: seo.metatags, seo.indexing, redirects (exact sources only)
Content: .md / .mdx pages under your content directory
Components: callouts, tabs, steps, cards, code groups, accordions, param/response fields, and the other built-ins listed under Components

Migration steps#

Copy config and content

Place your existing docs.json at the project root and your pages under content/docs (or set contentDir in shiso.config.ts to match your old layout).

Point the schema at Shiso

Change the $schema value so editor validation matches what this project implements:

{
  "$schema": "./node_modules/@umami/shiso/docs.schema.json"
}

Set the site origin

Add siteUrl to a shiso.config.ts file at the project root so canonical URLs, Open Graph tags, the sitemap, and AI contextual links work:

import { defineConfig } from '@umami/shiso/config';

export default defineConfig({
  siteUrl: 'https://docs.example.com',
});

Validate

Run the config check and fix anything it reports:

pnpm check

Preview and build

pnpm dev
pnpm build

Behavior differences to expect#

The pages under Configuration describe Shiso's complete configuration surface. Remove other settings from the migrated docs.json and set theme to "shiso", or omit it.

Versions and languages#

If your config uses navigation.versions or navigation.languages, Shiso builds every entry and adds version and language selectors to the header. Each entry must reference its own content files; page references determine the URLs, so keep older versions and translations in their own directories. See Versions and Languages for examples.

Redirects#

Use an exact source value for each redirect; wildcard patterns are not supported. Sources must include the full path (including the docs prefix), for example /docs/old-page.

Hosted features that do not apply#

Mintlify-hosted services — hosted search, analytics integrations, API playgrounds, authentication, and live GitHub star counts — are not part of Shiso. Built-in replacements:

Mintlify feature	Shiso equivalent
Hosted search	Client-side search (`⌘K` / `Ctrl K`)
AI chat / MCP	Markdown export + `contextual` menu
Custom domain hosting	Deploy `dist/client` to any static host

Icons#

Icon names still come from the lucide set. Names are collected from your content and docs.json at build time — no separate icon registration step.

Content checklist#

Every page listed under navigation has a matching file (.md or .mdx).
Image and asset paths resolve under public/ (for example /images/hero.png → public/images/hero.png).
Frontmatter uses title and optional description; add noindex or timestamp where you need page-level SEO or last-updated overrides. related carries over and renders a "Related topics" list above the previous/next links.
Components you used still exist in Shiso — see Components. Unsupported custom components need a local replacement or plain Markdown.

After the move#

Deployment — ship dist/client
SEO and redirects — confirm sitemap, redirects, and 404 behavior
Search and AI — enable the contextual menu if you want copy/view/AI actions on every page

Last updated on Aug 23, 2026

PreviousDeployment NextFrom Docusaurus