Warum unterscheidet sich die lokale Darstellung von Rouge von der Darstellung auf GitHub Pages?

Melden

Dass die Darstellung von Rouge (dem Syntax-Highlighter, der standardmäßig von Jekyll verwendet wird) lokal anders aussieht als auf GitHub Pages, ist ein häufiges Problem. Es gibt dafür meist drei Hauptgründe: Versionsunterschiede, fehlendes/anderes CSS oder Konfigurationsabweichungen.

Hier sind die Details zu den Ursachen und wie du sie behebst:

1. Unterschiedliche Software-Versionen

GitHub Pages läuft in einer streng kontrollierten Umgebung mit spezifischen Versionen von Ruby-Gems (wie Jekyll und Rouge). Wenn deine lokale Version neuer oder älter ist als die von GitHub, kann das HTML-Markup, das Rouge erzeugt, leicht variieren.

  • Die Lösung: Nutze das github-pages Gem in deinem Projekt, um die Umgebung von GitHub exakt lokal zu simulieren.
  • Prüfe dein Gemfile. Es sollte so aussehen:
    gem "github-pages", group: :jekyll_plugins
  • Führe lokal immer bundle exec jekyll serve aus (statt nur jekyll serve), um sicherzustellen, dass die im Gemfile.lock definierten Versionen genutzt werden.

2. Das CSS-Theme fehlt oder unterscheidet sich

Rouge generiert nur das HTML (viele <span>-Tags mit Klassen wie .k, .nf, .s2). Das eigentliche Aussehen (Farben, Schriftart) kommt von einer CSS-Datei.

  • Lokal vs. GitHub: Vielleicht hast du lokal ein Stylesheet eingebunden, das auf GitHub Pages nicht korrekt geladen wird (z. B. wegen eines falschen Pfads/BaseURL).
  • Generiertes CSS: Wenn du ein eigenes Rouge-Theme generiert hast (mit rougify style ...), stelle sicher, dass diese CSS-Datei im Repository eingecheckt ist und im Header deiner HTML-Layouts korrekt verlinkt wurde.
  • Standard-Themes: Manche Jekyll-Themes bringen eigene Syntax-Styles mit. Wenn GitHub Pages ein Standard-Theme (wie Minima) verwendet, dein lokales Setup aber eine leicht andere Version davon hat, unterscheiden sich die Farben.

3. Konfiguration in der _config.yml

Es gibt Einstellungen, die beeinflussen, wie der Markdown-Interpreter (Kramdown) mit Rouge interagiert.

  • Prüfe deine _config.yml:
    kramdown:
  syntax_highlighter: rouge
  syntax_highlighter_opts:
    # Hier könnten Optionen stehen, die lokal anders interpretiert werden
    block_code_build_lines: true
  • GitHub Pages hat oft Standardeinstellungen für Kramdown, die von deinen lokalen Standardwerten abweichen könnten.

4. Cache-Probleme

Manchmal liegen die Unterschiede einfach an veralteten Dateien im Browser-Cache oder im lokalen _site-Ordner.

  • Lösung: Lösche lokal den Ordner .jekyll-cache und _site und baue neu. Leere den Browser-Cache für deine GitHub-Pages-URL.

5. Pfad-Probleme (Asset Pipeline)

Ein Klassiker: Auf GitHub Pages liegt deine Seite oft unter einer Unter-URL (z. B. nutzername.github.io/projektname/). Wenn dein CSS-Pfad für das Syntax-Highlighting absolut angegeben ist (/assets/css/syntax.css), findet GitHub die Datei nicht, weil sie unter /projektname/assets/css/syntax.css liegen müsste.

  • Check: Öffne die Entwicklertools im Browser (F12) auf der GitHub-Pages-Seite und schaue in der Konsole nach "404 Not Found" Fehlern für CSS-Dateien.

Zusammenfassung: So gleichst du es an

  1. Gleiche Versionen: Nutze das github-pages Gem lokal.
  2. CSS kontrollieren: Stelle sicher, dass die CSS-Klassen von Rouge (z.B. .highlight .k { color: #... }) in deiner CSS-Datei definiert sind und diese Datei auf GitHub geladen wird.
  3. Baseurl: Achte darauf, dass Links zu CSS-Dateien in deinem Layout so aussehen: {{ "/assets/css/syntax.css" | relative_url }}.

Tipp: Du kannst ein Rouge-Stylesheet selbst generieren, um volle Kontrolle zu haben:

rougify style monokai.sublime > assets/css/syntax.css

Und dieses dann explizit in deinem HTML-Header einbinden.

0