docmd bietet ein robustes, Dateisystem-bewusstes Verlinkungssystem. Schreiben Sie Links zu Ihren Quell-.md-Dateien ganz natürlich — in jedem Format, das Sie bevorzugen — und die Engine normalisiert diese automatisch in saubere, SEO-optimierte URLs für die Produktion.

Wie die URL-Normalisierung funktioniert

Während des Build-Prozesses wendet die Engine eine konsistente Reihe von Regeln auf jeden internen Link an — egal ob in Markdown-Texten, Button-Containern, Tags oder der Navigationskonfiguration:

Interne Link-Auflösung

Verlinken Sie auf andere Seiten in Ihrer Dokumentation über relative Pfade zu den Quell-.md-Dateien. Die Engine löst diese unabhängig von der Verzeichnistiefe korrekt auf.

Abschnitts-Anker (Deep Linking)

Navigieren Sie direkt zu bestimmten Überschriften mit Standard-URL-Hash-Fragmenten.

• Anker auf derselben Seite: [Zum Roadmap springen](#project-roadmap)
• Anker auf anderer Seite: [CLI-Flags prüfen](../cli-commands.md#available-flags)

Hash-Fragmente bleiben während des Normalisierungsprozesses erhalten. Der obige Link wird in der Produktion als ../cli-commands/#available-flags gerendert.

Links in einem neuen Tab öffnen

Verwenden Sie das Präfix external: bei jedem Link, um das Öffnen in einem neuen Tab zu erzwingen. Dies funktioniert universell — in Standard-Markdown-Links, Button-Containern, Tags und überall dort, wo Sie eine URL schreiben können.

<!-- Öffnen in neuem Tab erzwingen -->
[In neuem Tab öffnen](external:./configuration/overview.md)

<!-- Externer Link zu GitHub -->
[GitHub](external:https://github.com/docmd-io/docmd)

Standardmäßig werden alle Links (einschließlich HTTP/HTTPS) im selben Fenster geöffnet. Verwenden Sie das Präfix external: nur, wenn Sie einen neuen Tab wünschen.

Das Präfix external: wird aus der gerenderten URL entfernt — es ist ein reines Signal für die Build-Zeit.

Verlinkung zu Rohdateien (Raw Files)

Standardmäßig entfernt die Engine .md-Erweiterungen und normalisiert Pfade. Wenn Sie tatsächlich auf eine rohe .md-Datei verlinken müssen (zum Beispiel eine herunterladbare Quelldatei), verwenden Sie das Präfix raw::

[Quellcode anzeigen](raw:docs/readme.md)

Das Präfix raw: umgeht die gesamte Normalisierung — die Erweiterung und der Pfad bleiben exakt so erhalten, wie sie geschrieben wurden. Wie bei external: wird das Präfix selbst aus der gerenderten URL entfernt.

Button-Container

Der ::: button-Container unterstützt dieselben Verlinkungskonventionen wie Standard-Markdown-Links — einschließlich der Präfixe external: und raw::

::: button "Erste Schritte" ./getting-started/quick-start.md icon:rocket

::: button "Auf GitHub anzeigen" https://github.com/docmd-io/docmd icon:github

::: button "Quelle herunterladen" raw:docs/readme.md icon:download

Tag-Links

Tags mit link:-Werten profitieren ebenfalls vom einheitlichen Normalisierer:

::: tag "v0.7.6" link:release-notes/0-7-6.md icon:tag color:#22c55e

::: tag "GitHub" link:https://github.com/docmd-io/docmd icon:github

::: tag "Extern öffnen" link:external:./configuration/overview.md icon:external-link

Navigationskonfiguration

Pfade, die in navigation.json und docmd.config.js definiert sind, werden ebenfalls zur Build-Zeit normalisiert. Sie können sie in jedem Format schreiben:

[
  { "title": "Overview", "path": "configuration/overview" },
  { "title": "Overview", "path": "configuration/overview.md" },
  { "title": "Overview", "path": "configuration/overview/" }
]

Alle drei obigen Einträge erzeugen dieselbe kanonische URL: /configuration/overview/.

Für Navigationselemente, die in einem neuen Tab geöffnet werden sollen, verwenden Sie das Flag external:

[
  {
    "title": "GitHub",
    "path": "https://github.com/docmd-io/docmd",
    "external": true
  }
]

<!-- Bevorzugt -->
[Lokalisierung](localisation/)

<!-- Funktioniert auch (auto-normalisiert) -->
[Lokalisierung](localisation/index.md)

Protokolle & Externe Ressourcen

Die Engine respektiert Standard-Browserprotokolle für externe Ressourcen. Diese Links werden niemals geändert.

• Globales HTTPS: [docmd Homepage](https://docmd.io) — öffnet im selben Tab (Präfix external: für neuen Tab verwenden)
• Mail-Protokoll: [Support-Kanal](mailto:help@docmd.io) — wird nicht in einem neuen Tab geöffnet
• Asset-Protokoll: [CLI-Binary herunterladen](/assets/bin/docmd-mac.zip) — wird nicht normalisiert

Referenzierung statischer Assets

Um Downloads bereitzustellen oder auf rohe Quelldateien zu verweisen, platzieren Sie diese im Verzeichnis assets/ Ihres Projekts. Der docmd-Builder stellt sicher, dass diese Dateien ohne Pfadänderungen in das Produktions-Root verschoben werden.

[Dokumentations-PDF herunterladen](/assets/pdf/handbook.pdf)
[Globale Konfiguration anzeigen](/assets/config/docmd.config.js)