Wie lassen sich Probleme bei der Einbindung von benutzerdefinierten CSS-Dateien in Couscous lösen?

Melden

Probleme bei der Einbindung von benutzerdefiniertem CSS in Couscous (einem statischen Seitengenerator für PHP/Markdown) liegen meist an der Konfiguration in der couscous.yml oder an fehlerhaften Pfadangaben.

Hier sind die gängigsten Lösungswege, um CSS-Probleme in Couscous zu beheben:

1. Die korrekte Konfiguration in der couscous.yml

Der häufigste Fehler ist, dass die CSS-Datei nicht in der Konfigurationsdatei registriert wurde. Couscous fügt CSS nicht automatisch hinzu, nur weil die Datei im Ordner liegt.

Stellen Sie sicher, dass Ihre couscous.yml den Abschnitt scripts (für CSS und JS) enthält:

# couscous.yml
scripts:
    - css/style.css

2. Die Verzeichnisstruktur prüfen

Couscous erwartet eine bestimmte Struktur. Standardmäßig werden alle Dateien im Projektverzeichnis in das Zielverzeichnis (.couscous/generated) kopiert.

Empfohlene Struktur:

mein-projekt/
├── couscous.yml
├── index.md
└── css/
    └── style.css

In diesem Fall muss der Pfad in der couscous.yml genau css/style.css lauten.

3. Absolute vs. Relative Pfade (BaseURL-Problem)

Wenn Ihr CSS auf der Startseite funktioniert, aber nicht auf Unterseiten (z. B. in Unterordnern), liegt das oft an den Pfaden. Couscous generiert statische HTML-Seiten. Wenn Sie ein eigenes Template verwenden, sollten Sie die Variable {{ baseUrl }} nutzen.

In Ihrem HTML-Template (layout.twig):

<link rel="stylesheet" href="{{ baseUrl }}/css/style.css">

Ohne {{ baseUrl }} sucht der Browser auf einer Unterseite wie docs/hilfe.html nach docs/css/style.css, was fehlschlägt.

4. Einbindung in ein eigenes Template

Wenn Sie ein Standard-Template (wie "Couscous-Template") überschreiben möchten, müssen Sie einen Ordner für Ihr Template erstellen (z. B. website/) und diesen in der couscous.yml angeben:

template:
    directory: website

Stellen Sie sicher, dass in Ihrer layout.twig innerhalb dieses Ordners der Platzhalter für CSS vorhanden ist oder Sie die Datei dort hartkodiert einbinden.

5. Cache-Probleme beim Generieren

Couscous speichert generierte Dateien zwischen. Manchmal werden Änderungen am CSS nicht sofort übernommen.

  • Löschen Sie den Ordner .couscous, falls er existiert.
  • Führen Sie den Befehl zum Generieren erneut aus:
    couscous generate
  • Nutzen Sie den integrierten Server, um Änderungen live zu sehen:
    couscous preview

6. Debugging mit den Browser-Entwicklertools

Wenn das CSS nicht geladen wird:

  1. Öffnen Sie die Seite im Browser.
  2. Drücken Sie F12 (Entwicklertools) -> Tab Netzwerk.
  3. Laden Sie die Seite neu (Strg + R).
  4. Suchen Sie nach der roten Zeile der CSS-Datei (Status 404).
  5. Prüfen Sie den Pfad, unter dem der Browser die Datei zu finden glaubt. Dies gibt meist den entscheidenden Hinweis, ob ein Ordner in der Pfadangabe fehlt.

Zusammenfassung der Checkliste:

  • [ ] Ist die CSS-Datei in der couscous.yml unter scripts: eingetragen?
  • [ ] Liegt die Datei physikalisch im richtigen Ordner?
  • [ ] Wird {{ baseUrl }} im Template verwendet, um Pfadprobleme auf Unterseiten zu vermeiden?
  • [ ] Wurde der lokale Cache (.couscous-Ordner) geleert?

Falls Sie ein spezifisches Template von GitHub nutzen, prüfen Sie bitte auch, ob dieses Template eventuell eigene Konfigurationsschlüssel für Stylesheets verlangt.

0