Migrations

Migrating from Docusaurus

Move a Docusaurus docs folder and sidebar into Shiso.

Docusaurus content is Markdown/MDX, so pages move over largely intact. The work is translating docusaurus.config.js and sidebars.js into a single docs.json, and swapping themed components for Shiso's built-ins.

What carries over#

Content: .md / .mdx files, GFM tables, task lists, frontmatter title and description
Admonitions: :::note, :::tip, :::info, :::warning, :::danger map one-to-one to Shiso callouts
Static assets: files from static/ move to public/ with the same URLs
Versioning and i18n: versioned_docs and i18n trees map to Versions and Languages

Migration steps#

Create a Shiso project

pnpm dlx create-shiso-app@latest my-docs

Copy content and assets

Move your docs/ files into content/docs and everything from static/ into public/.

Rebuild the sidebar as navigation

Translate sidebars.js into docs.json navigation. Categories become groups, doc ids become page paths:

{
  "navigation": {
    "groups": [
      {
        "group": "Getting started",
        "pages": ["index", "installation"]
      }
    ]
  }
}

Shiso has no sidebar_position — order comes from the pages arrays.

Move branding

Map themeConfig values into docs.json: title → name, navbar.logo → logo, navbar items → navbar.links, footer links → footer.

Convert components

Replace themed imports with Shiso built-ins (no imports needed), then validate and build:

pnpm check
pnpm build

Component mapping#

Docusaurus	Shiso
`:::note` / `:::tip` / `:::info` / `:::warning` / `:::danger`	`<Note>` / `<Tip>` / `<Info>` / `<Warning>` / `<Danger>`
`<Tabs>` + `<TabItem value label>` from `@theme`	`<Tabs>` + `<Tab title>`, no imports
`<details>` / `<summary>`	`<Accordion title>`
Multi-language code tabs	`<CodeGroup>`
`DocCardList`	`<Columns>` of `<Card>`s

Admonition syntax (:::note) must be rewritten as components — Shiso uses MDX components rather than directive syntax:

<Note>
  Neutral supplemental information.
</Note>

Frontmatter differences#

Docusaurus field	Shiso equivalent
`title`, `description`	Same
`sidebar_label`	`title` on the page object in `docs.json`
`sidebar_position`	Order in the `pages` array
`slug`, `id`	File path determines the URL; use redirects for moved pages
`draft`	Remove the page from navigation, or set `noindex: true`

Not carried over#

Plugins and swizzled components — custom React components need a plain Markdown or built-in component replacement
Blog — Shiso is docs-only
Algolia DocSearch — replaced by built-in client-side search (⌘K / Ctrl K)

After the move#

Deployment — ship dist/client
SEO and redirects — map old slug values to new paths
Versions — recreate versioned docs if you had them

Last updated on Aug 23, 2026

PreviousFrom Mintlify NextFrom Nextra