Warum werden Markdown-Dateien von Couscous manchmal nicht korrekt in HTML übersetzt?

Melden

Couscous ist ein statischer Website-Generator, der speziell für PHP-Dokumentationen entwickelt wurde. Wenn Markdown-Dateien nicht wie erwartet in HTML umgewandelt werden, liegt das meist an einer der folgenden Ursachen:

1. Konflikte mit der Twig-Syntax

Couscous nutzt Twig als Template-Engine. Das ist Fluch und Segen zugleich:

  • Das Problem: Wenn dein Markdown-Text Zeichenfolgen wie {{ ... }} oder {% ... %} enthält (was häufig in Code-Beispielen vorkommt), versucht Couscous, diese als Twig-Befehle auszuführen. Wenn die Variable nicht existiert, bricht der Prozess ab oder zeigt nichts an.
  • Lösung: Nutze den {% verbatim %}-Tag um Code-Blöcke, die geschweifte Klammern enthalten:
    {% verbatim %}
```javascript
if (a == {{ value }}) { ... }

    {% endverbatim %}

2. Fehlerhaftes YAML Front Matter

Am Anfang von Markdown-Dateien kann ein Metadaten-Block (Front Matter) stehen.

  • Das Problem: Wenn dieser Block nicht exakt mit drei Bindestrichen --- beginnt und endet oder wenn die Einrückungen (Indentations) im YAML-Code falsch sind, kann die Datei nicht verarbeitet werden.
  • Lösung: Prüfe, ob das YAML valide ist. Es dürfen keine Leerzeichen vor den --- stehen.

3. Markdown-Dialekte (Flavors)

Couscous verwendet intern meist den cebe/markdown-Parser.

  • Das Problem: Nicht alle Markdown-Features (wie z. B. GitHub Flavored Markdown Tabellen oder Checklisten) sind standardmäßig aktiviert oder werden exakt so unterstützt wie auf GitHub.
  • Lösung: Überprüfe in der couscous.yml, welcher Parser konfiguriert ist, und halte dich an die Standard-Syntax.

4. Probleme mit der couscous.yml

Die zentrale Konfigurationsdatei steuert, wie die Seite generiert wird.

  • Das Problem: Wenn das Verzeichnis für die Templates falsch angegeben ist oder die directory-Struktur in der couscous.yml nicht mit deiner Ordnerstruktur übereinstimmt, findet das Tool die Dateien nicht oder wendet das falsche Layout an.
  • Lösung: Validierung der Pfade in der couscous.yml.

5. Relative Pfade und Links

  • Das Problem: Markdown-Links zu anderen Dateien (z.B. [Link](setup.md)) funktionieren lokal, aber nach der Umwandlung in HTML müssen sie oft auf .html enden ([Link](setup.html)), damit sie im Browser funktionieren.
  • Lösung: Couscous versucht dies oft automatisch zu korrigieren, aber bei komplexen Unterordner-Strukturen kann dies scheitern. Nutze absolute Pfade ausgehend vom Root-Verzeichnis, falls möglich.

6. Fehlende Skripte oder Stylesheets

  • Das Problem: Die Markdown-Datei wird technisch korrekt in HTML übersetzt, sieht aber „kaputt“ aus, weil CSS-Dateien nicht geladen werden (404-Fehler).
  • Lösung: Prüfe in der Browser-Konsole (F12), ob CSS- oder JS-Dateien fehlen. Das liegt oft an einer falsch gesetzten baseUrl in der Konfiguration, besonders wenn die Seite in einem Unterordner oder auf GitHub Pages gehostet wird.

7. Kodierung (UTF-8)

  • Das Problem: Wenn Dateien in einem anderen Format als UTF-8 (ohne BOM) gespeichert sind, können Sonderzeichen (Umlaute) die Verarbeitung stoppen oder zu kryptischen Zeichen führen.
  • Lösung: Stelle sicher, dass dein Editor die Dateien als UTF-8 speichert.

Wie man den Fehler findet:

Lasse Couscous im Debug-Modus laufen, um detaillierte Fehlermeldungen zu erhalten:

couscous generate -v

Oder starte den lokalen Server, um Änderungen live zu sehen:

couscous preview

Meistens zeigen die Fehlermeldungen im Terminal direkt auf die Zeile im Markdown-Dokument, die den Fehler verursacht (oft ein Twig-Syntax-Fehler).

0