Migration
Astro Starlight

Von Astro Starlight migrieren zu docmd

Starlight ist ein hervorragendes Dokumentations-Theme, das auf dem Astro-Framework basiert. docmd bietet eine ähnliche Standarderfahrung ohne JavaScript, macht jedoch die Konfiguration eines vollständigen Web-Frameworks (Astro) überflüssig, was die Lernkurve für technische Redakteure drastisch reduziert.

Schritt 1: Führen Sie die Migrations-Engine aus

Führen Sie den folgenden Befehl im Hauptverzeichnis Ihres bestehenden Starlight-Projekts aus (dort, wo sich Ihre astro.config.mjs befindet):

npx @docmd/core migrate --starlight

Was passiert automatisch

Backup: Ihr gesamtes Projekt wird sicher in ein neues starlight-backup/-Verzeichnis verschoben.
Inhaltsmigration: Starlight speichert die Dokumentation in src/content/docs/. Die Migrations-Engine extrahiert dieses spezifische Verzeichnis automatisch und verschiebt seinen Inhalt zur Nutzung durch docmd in den Stammordner docs/.
Konfigurationsgenerierung: Eine docmd.config.js wird generiert, die Ihren Website-title aus der Starlight-Integration innerhalb der astro.config.mjs extrahiert.

Schritt 2: Testen Sie das Setup

Sobald der Befehl abgeschlossen ist, können Sie Ihre Inhalte in docmd in der Vorschau anzeigen:

npx @docmd/core dev

Ihre Markdown-Dateien werden kompiliert, aber Ihre Navigations-Sidebar bleibt zunächst leer.

Schritt 3: Manuelle Konfiguration

1. Navigations-Setup

Starlight definiert die Navigation in der astro.config.mjs über das Array sidebar.

Aktion erforderlich: Sie müssen eine navigation.json in Ihrem neuen docs/-Ordner erstellen.

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" }
    ]
  }
]

2. Astro-Komponenten ersetzen (MDX/Markdoc)

Starlight verwendet Astro-Komponenten (<Tabs>, <Card> usw.), die über MDX oder Markdoc eingebettet sind. Da sich docmd auf reine Markdown-Syntax anstelle von UI-Komponenten verlässt, müssen diese konvertiert werden.

Aktion erforderlich: Ersetzen Sie Astro-Komponenten durch docmd Container.

Beispiel: Tabs konvertieren

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"
Sirius, Vega, Betelgeuse

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

Beispiel: Admonitions (Asides) konvertieren