Migration
MkDocs

Migration von MkDocs zu docmd

MkDocs ist ein beliebter Python-basierter Generator. docmd bietet eine ähnliche Markdown-First-Erfahrung. Es verwendet Node.js/Bun für unglaublich schnelle Builds ohne komplexe Python-Erweiterungen.

Schritt 1: Migrations-Engine ausführen

Führen Sie den folgenden Befehl im Stammverzeichnis Ihres bestehenden MkDocs-Projekts aus:

npx @docmd/core migrate --mkdocs

Was automatisch passiert

Backup: Ihr gesamtes Projekt wird sicher in ein neues Verzeichnis mkdocs-backup/ verschoben.
Content-Migration: Ihr docs/-Ordner wird in das Stammverzeichnis zurückgespielt, damit docmd ihn verwenden kann.
Config-Generierung: Eine docmd.config.json wird generiert, die Ihre site_name aus mkdocs.yml extrahiert.

Schritt 2: Setup testen

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 wird leer sein.

Schritt 3: Manuelle Konfiguration

MkDocs verwendet mkdocs.yml, um Site-Navigation und Erweiterungen zu definieren. Sie müssen dieses Setup manuell für docmd übersetzen.

1. Navigations-Einrichtung

In MkDocs ist die Navigation streng im Schlüssel nav der mkdocs.yml definiert.

Erforderliche Aktion: Erstellen Sie eine navigation.json in Ihrem docs/-Ordner.

mkdocs.yml

nav:
  - Startseite: index.md
  - Leitfaden:
    - Einrichtung: setup.md
    - Verwendung: usage.md

navigation.json

[
  {
    "title": "Startseite",
    "path": "/"
  },
  {
    "title": "Leitfaden",
    "collapsible": true,
    "children": [
      { "title": "Einrichtung", "path": "/setup" },
      { "title": "Verwendung", "path": "/usage" }
    ]
  }
]

2. Python-Markdown-Erweiterungen ersetzen

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

Erforderliche Aktion: Konvertieren Sie MkDocs-spezifische Erweiterungs-Syntax in docmds native Container.

Beispiel: Admonitions konvertieren

MkDocs (PyMdown):

!!! note "Optionaler Titel"
    Dies ist ein Admonition-Inhaltsblock.

Manuelle Konvertierung erforderlich

MkDocs verwendet !!!-Syntax für Admonitions, die sich von docmds :::-Syntax unterscheidet. Sie müssen diese manuell konvertieren oder ein Suchen-und-Ersetzen-Tool verwenden.

Mapping:

!!! note → ::: callout info oder :::note
!!! tip → ::: callout tip oder :::tip
!!! warning → ::: callout warning oder :::warning
!!! danger → ::: callout danger oder :::danger
!!! example → ::: callout info

docmd:

::: callout info "Optionaler Titel"
Dies ist ein Admonition-Inhaltsblock.
:::

Beispiel: Tabs konvertieren

MkDocs (SuperFences):

=== "Tab 1"
    Inhalt für Tab 1.

=== "Tab 2"
    Inhalt für Tab 2.