Warum erkennt Couscous neu hinzugefügte Verzeichnisse im Projektordner manchmal nicht automatisch?

Melden

Dass Couscous (ein statischer Seitengenerator für PHP, der oft für Dokumentationen genutzt wird) neu hinzugefügte Verzeichnisse nicht erkennt, kann verschiedene Ursachen haben. Hier sind die häufigsten Gründe und Lösungen:

1. Der "Preview"-Modus erkennt keine Strukturänderungen

Wenn du Couscous mit dem Befehl couscous preview ausführst, startet ein interner Webserver mit einem "Watcher". Dieser Watcher reagiert sehr zuverlässig auf Änderungen innerhalb bestehender Dateien.

  • Das Problem: Viele Datei-Watcher haben Schwierigkeiten, die Erstellung komplett neuer Verzeichnisse in Echtzeit zu registrieren, da sie nur die bestehenden Datei-Handles überwachen.
  • Lösung: Beende den Prozess (Strg+C) und starte couscous preview neu.

2. Fehlende Index-Datei (index.md oder README.md)

Couscous generiert das Menü und die Struktur basierend auf den vorhandenen Markdown-Dateien.

  • Das Problem: Wenn du ein neues Verzeichnis erstellst, dieses aber leer ist oder keine "Einstiegsdatei" enthält, ignoriert Couscous den Ordner oft in der Navigation.
  • Lösung: Stelle sicher, dass in dem neuen Verzeichnis mindestens eine README.md oder index.md liegt.

3. Konfiguration in der couscous.yml

Couscous erlaubt es, Verzeichnisse explizit ein- oder auszuschließen.

  • Das Problem: Überprüfe deine couscous.yml. Wenn du dort unter exclude Muster definiert hast (z. B. Vendor-Ordner oder bestimmte Präfixe), könnte dein neues Verzeichnis versehentlich darunter fallen.
  • Lösung: Prüfe die Abschnitte include und exclude in deiner Konfigurationsdatei.

4. Cache-Probleme im Ausgabeverzeichnis

Couscous generiert die fertige Website standardmäßig in ein temporäres Verzeichnis oder (beim Deployment) in den gh-pages Branch.

  • Das Problem: Manchmal bleiben alte Zustände im lokalen Cache-Ordner (.couscous/generated) hängen, was dazu führt, dass die neue Struktur nicht korrekt gerendert wird.
  • Lösung: Lösche den versteckten Ordner .couscous in deinem Projektverzeichnis, um einen komplett sauberen Build zu erzwingen.

5. Dateiberechtigungen

Gerade wenn Verzeichnisse über IDEs, Docker-Container oder andere Benutzer angelegt werden, können die Leserechte fehlen.

  • Das Problem: Couscous läuft mit den Rechten des aktuellen Nutzers. Wenn dieser keine Leserechte für den neuen Ordner hat, wird er übersprungen.
  • Lösung: Prüfe mit ls -l, ob der Ordner für den ausführenden User lesbar ist.

6. Case Sensitivity (Groß-/Kleinschreibung)

Couscous basiert auf PHP. Wenn du auf einem System arbeitest, das case-sensitive ist (wie Linux), und in deiner Konfiguration oder in Links auf eine bestimmte Schreibweise achtest, die im Dateisystem anders aussieht, kann das zu Fehlern führen.

  • Lösung: Achte auf konsistente Kleinschreibung bei Verzeichnisnamen.

Zusammenfassung der ersten Schritte zur Fehlerbehebung:

  1. Neustart: Beende couscous preview und starte es neu.
  2. Datei anlegen: Erstelle eine README.md im neuen Ordner.
  3. Clean Build: Lösche den .couscous-Ordner.
  4. Konfiguration prüfen: Schau in die couscous.yml, ob der Ordner ignoriert wird.