Was sind die häufigsten Ursachen für fehlerhafte relative Links in der generierten Couscous-Dokumentation?

Melden

Couscous ist ein statischer Seitengenerator, der Markdown-Dateien in HTML-Websites umwandelt. Fehlerhafte relative Links sind eines der häufigsten Probleme bei der Generierung.

Hier sind die häufigsten Ursachen für dieses Problem:

1. Die Endung .md vs. .html

In deinen Markdown-Dateien verlinkst du oft auf andere Markdown-Dateien (z. B. [Kontakt](kontakt.md)).

  • Das Problem: Couscous wandelt kontakt.md in kontakt.html um. Wenn der Link im Markdown jedoch hart codiert auf .md verweist und Couscous diesen nicht automatisch korrigiert (oder die Konfiguration dies verhindert), führt der Link im Browser ins Leere.
  • Lösung: Couscous versucht normalerweise, diese Links zu fixen. Wenn das fehlschlägt, prüfe, ob die Datei tatsächlich generiert wurde und ob die Link-Syntax dem Standard entspricht.

2. Fehlende oder falsche baseUrl

Dies ist die häufigste Ursache, wenn die Seite nicht im Root-Verzeichnis einer Domain liegt (z. B. auf GitHub Pages unter nutzer.github.io/projekt/).

  • Das Problem: Wenn du einen Link wie /css/style.css oder /bilder/test.png verwendest, sucht der Browser im Root der Domain (nutzer.github.io/css/...), nicht im Projektordner.
  • Lösung: In der couscous.yml muss die baseUrl korrekt gesetzt sein:
    baseUrl: /projektname/

    Verwende dann in den Templates Variablen wie {{ baseUrl }}, um Pfade dynamisch zu generieren.

3. Verzeichnisstruktur und index.md

Couscous wandelt Ordnerstrukturen um. Ein häufiger Stolperstein ist die Behandlung von README.md oder index.md.

  • Das Problem: Ein Link von docs/guide.md zurück zur Startseite im Hauptverzeichnis muss ../index.html (oder nur ../) sein. Wenn man sich in der Ordnertiefe vertut (z. B. ../../ statt ../), bricht der Link.
  • Besonderheit: Couscous macht aus ordner/README.md oft ordner/index.html. Wenn man nun direkt auf README.md verlinkt, kann es zu Problemen mit dem Slash am Ende der URL kommen.

4. Case Sensitivity (Groß-/Kleinschreibung)

  • Das Problem: Auf deinem lokalen Windows- oder Mac-Rechner spielt es oft keine Rolle, ob eine Datei Bild.png oder bild.png heißt. Sobald die Dokumentation auf einen Linux-Server (wie GitHub Pages) hochgeladen wird, ist Bild.png ungleich bild.png.
  • Lösung: Achte strikt auf Kleinschreibung bei allen Dateinamen und Links.

5. Links zu Assets (Bilder, CSS, JS)

  • Das Problem: Bilder werden oft mit relativem Pfad eingebunden (z. B. ![Logo](../img/logo.png)). Wenn die Markdown-Datei in der HTML-Ausgabe in einer anderen Ordnertiefe landet als erwartet, findet der Browser das Bild nicht.
  • Lösung: Nutze absolute Pfade ausgehend vom Projekt-Root in Kombination mit der baseUrl.

6. "Pretty URLs" vs. Standard-Links

Couscous kann so konfiguriert werden, dass es "schöne" URLs erzeugt (z. B. domain.com/seite statt domain.com/seite.html).

  • Das Problem: Wenn Pretty URLs aktiviert sind, ändert sich die relative Ebene der Datei technisch gesehen (da der Browser denkt, er befinde sich in einem Unterordner). Relative Links wie ./bild.png funktionieren dann plötzlich nicht mehr, weil der Browser das Bild "einen Ordner tiefer" sucht.

7. Manuelle Verlinkung in Templates (Twig)

Couscous nutzt Twig als Template-Engine.

  • Das Problem: Wenn du im HTML-Layout (default.html) Links hart codierst, ohne die Twig-Variablen für die Pfadberechnung zu nutzen, funktionieren diese Links nur auf der Startseite, aber nicht auf Unterseiten.
  • Lösung: Nutze Twig-Filter oder Variablen, um Pfade relativ zur aktuellen Seite zu berechnen.

Zusammenfassende Checkliste zur Fehlerbehebung:

  1. couscous.yml prüfen: Ist baseUrl gesetzt?
  2. Relative Pfade zählen: Stimmt die Anzahl der ../ für die aktuelle Ordnertiefe?
  3. Kleinschreibung: Sind alle Datei- und Ordnernamen klein geschrieben?
  4. Generierte HTML prüfen: Schau in den output-Ordner (meist .couscous/generated). Sieht die Struktur dort so aus, wie du es in den Links erwartest?
  5. Browser-Konsole: Drücke F12 und schau unter "Network", welcher Pfad genau aufgerufen wird (404 Fehler). Das verrät meist sofort, wo der Denkfehler im Pfad liegt.
0