Migrating from Astro Starlight : docmd docs

Migración
Astro Starlight

Starlight is a documentation theme built on Astro. docmd delivers a similar zero-JavaScript-by-default experience without requiring full web framework configurations or complex Astro integrations.

1. Run the Migration Engine

Run the following command at the root of your existing Starlight project:

npm

pnpm

yarn

Bun

npx @docmd/core migrate --starlight

pnpm dlx @docmd/core migrate --starlight

yarn dlx @docmd/core migrate --starlight

bunx @docmd/core migrate --starlight

What Happens Automatically

Backup: Your entire project directory (excluding node_modules, .git, package.json, and lockfiles) is backed up safely into a new starlight-backup/ directory.
Content Migration: Starlight stores documentation in src/content/docs/. The migration engine extracts this folder and moves its contents to the root docs/ folder.
Config Generation: A docmd.config.json is generated, extracting your site title from the Starlight integration inside astro.config.mjs or astro.config.ts.

2. Preview the Migration Output

Preview your Markdown content in docmd immediately:

npm

pnpm

yarn

Bun

npx @docmd/core dev

pnpm dlx @docmd/core dev

yarn dlx @docmd/core dev

bunx @docmd/core dev

3. Manual Configuration & Component Replacement

Navigation Setup

Starlight defines navigation sidebars in astro.config.mjs via the sidebar array. Create a navigation.json inside your docs/ directory:

Starlight (astro.config.mjs):

sidebar: [
  {
    label: "Guides",
    items: [
      { label: "Setup", link: "/guides/setup/" }
    ]
  }
]

docmd (navigation.json):

[
  {
    "title": "Guides",
    "collapsible": true,
    "children": [
      { "title": "Setup", "path": "/guides/setup" }
    ]
  }
]

Replacing Astro Components (MDX / Markdoc)

Starlight uses Astro components embedded via MDX or Markdoc. Replace these with native docmd Containers.

Converting Tab Components

Starlight:

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs>
  <TabItem label="Stars">Sirius, Vega, Betelgeuse</TabItem>
  <TabItem label="Moons">Io, Europa, Ganymede</TabItem>
</Tabs>

docmd:

::: tabs
== tab "Stars" icon:sparkles
Sirius, Vega, Betelgeuse

== tab "Moons" icon:moon
Io, Europa, Ganymede
:::

Converting Asides (Admonitions)

Starlight:

:::note[Optional Title]
Some note content.
:::

docmd:

::: callout info "Optional Title"
Some note content.
:::

Frontmatter Mapping

Starlight enforces strict frontmatter typing via Astro content collections. If you used hero or banner frontmatter properties for landing pages, replace them with docmd’s native Hero Sections written directly in the Markdown body.

Next Steps

Explore docmd’s built-in Search plugin. While Starlight relies on Pagefind integration, docmd includes a fast, zero-config local search indexer out of the box.