Migrar desde Astro Starlight : docmd docs

Migración
Astro Starlight

Starlight es un tema de documentación creado sobre Astro. docmd ofrece una experiencia similar de cero JavaScript por defecto sin requerir configuraciones completas de frameworks web ni complejas integraciones de Astro.

1. Ejecutar el motor de migración

Ejecuta el siguiente comando en la raíz de tu proyecto existente de Starlight:

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

Qué sucede automáticamente

Copia de seguridad: Todo el directorio de tu proyecto (excluyendo node_modules, .git, package.json y archivos de bloqueo) se respalda de forma segura en un nuevo directorio starlight-backup/.
Migración de contenido: Starlight almacena la documentación en src/content/docs/. El motor de migración extrae esta carpeta y mueve su contenido a la carpeta raíz docs/.
Generación de configuración: Se genera un docmd.config.json, extrayendo el title de tu sitio de la integración de Starlight dentro de astro.config.mjs o astro.config.ts.

2. Previsualizar la salida de la migración

Previsualiza tu contenido Markdown en docmd de inmediato:

npm

pnpm

yarn

Bun

npx @docmd/core dev

pnpm dlx @docmd/core dev

yarn dlx @docmd/core dev

bunx @docmd/core dev

3. Configuración manual y reemplazo de componentes

Configuración de navegación

Starlight define las barras laterales de navegación en astro.config.mjs a través del array sidebar. Crea un archivo navigation.json dentro de tu directorio docs/:

Starlight (astro.config.mjs):

sidebar: [
  {
    label: "Guías",
    items: [
      { label: "Configuración", link: "/guides/setup/" }
    ]
  }
]

docmd (navigation.json):

[
  {
    "title": "Guías",
    "collapsible": true,
    "children": [
      { "title": "Configuración", "path": "/guides/setup" }
    ]
  }
]

Reemplazar componentes Astro (MDX / Markdoc)

Starlight utiliza componentes Astro incrustados a través de MDX o Markdoc. Reemplázalos con los Contenedores nativos de docmd.

Convertir componentes de pestañas

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
::: /tabs

Convertir llamadas de atención (asides)

Starlight:

:::note[Título opcional]
Algún contenido de nota.
:::

docmd:

::: callout info title:"Título opcional"
Algún contenido de nota.
::: /callout

Mapeo de frontmatter

Starlight exige un tipado estricto de frontmatter a través de las colecciones de contenido de Astro. Si utilizabas propiedades de frontmatter como hero o banner para páginas de inicio, reemplázalas con las Secciones Hero nativas de docmd redactadas directamente en el cuerpo de Markdown.

Siguientes pasos

Explora el plugin de búsqueda integrado de docmd. Mientras que Starlight depende de la integración con Pagefind, docmd incluye un indexador de búsqueda local rápido y sin configuración predeterminada listo para usar.