Migration
MkDocs

Von MkDocs migrieren zu docmd

MkDocs, insbesondere in Kombination mit dem Material-Theme, ist ein beliebter Python-basierter Dokumentationsgenerator. docmd bietet eine ähnliche, auf Markdown fokussierte Erfahrung, verwendet jedoch Node.js/Bun für extrem schnelle Builds und bietet umfangreiche interaktive Funktionen, ohne dass komplexe Python-Erweiterungen erforderlich sind.

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

Führen Sie den folgenden Befehl im Hauptverzeichnis Ihres bestehenden MkDocs-Projekts aus (dort, wo sich Ihre mkdocs.yml befindet):

npx @docmd/core migrate --mkdocs

Was passiert automatisch

Backup: Ihr gesamtes Projekt wird sicher in ein neues mkdocs-backup/-Verzeichnis verschoben.
Inhaltsmigration: Ihr docs/-Ordner wird im Stammverzeichnis wiederhergestellt, damit docmd ihn verwenden kann.
Konfigurationsgenerierung: Eine docmd.config.js wird generiert, die den site_name Ihrer Website aus Ihrer mkdocs.yml 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

MkDocs verwendet die mkdocs.yml, um die Navigation und die Erweiterungen der Website zu definieren. Sie müssen diese Einrichtung auf docmd übertragen.

1. Navigations-Setup

In MkDocs wird die Navigation streng unter dem Schlüssel nav in der mkdocs.yml definiert.

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

MkDocs (mkdocs.yml):

nav:
  - Home: index.md
  - Guide:
    - Setup: setup.md
    - Usage: usage.md

docmd (navigation.json):

[
  {
    "title": "Home",
    "path": "/"
  },
  {
    "title": "Guide",
    "collapsible": true,
    "children": [
      { "title": "Setup", "path": "/setup" },
      { "title": "Usage", "path": "/usage" }
    ]
  }
]

2. Python-Markdown-Erweiterungen ersetzen

Wenn Sie “Material for MkDocs” verwendet haben, haben Sie sich wahrscheinlich auf Python-Markdown-Erweiterungen wie PyMdown Extensions für Tabs, Admonitions oder Aufgabenlisten verlassen.

Aktion erforderlich: Konvertieren Sie die MkDocs-spezifische Erweiterungssyntax in die nativen Container von docmd.

Beispiel: Admonitions (Callouts) konvertieren

MkDocs (PyMdown):

!!! note "Optional Title"
    This is an admonition content block.

docmd:

::: note "Optional Title"
This is an admonition content block.
:::

Beispiel: Tabs konvertieren

MkDocs (SuperFences):

=== "Tab 1"
    Content for tab 1.

=== "Tab 2"
    Content for tab 2.