Skip to main content

Fehlerbehebung bei Jekyll-Build-Fehlern für GitHub Pages-Websites

Mithilfe der Jekyll-Build-Fehlermeldungen kannst du Probleme auf deiner GitHub Pages-Website beheben.

Wer kann dieses Feature verwenden?

GitHub Pages ist in öffentlichen Repositorys mit GitHub Free und GitHub Free für Organisationen sowie in öffentlichen und privaten Repositorys mit GitHub Pro, GitHub Team, GitHub Enterprise Cloud und GitHub Enterprise Server verfügbar.

Fehlerbehebung bei Build-Fehlern

Wenn beim Erstellen deiner GitHub Pages-Website (lokal oder auf GitHub Enterprise Server) mit Jekyll ein Fehler auftritt, kannst du die Fehlerbehebung mithilfe der Fehlermeldungen durchführen. Weitere Informationen zu Fehlermeldungen und deren Anzeige findest du unter Informationen zu Jekyll-Build-Fehler für GitHub Pages-Websites.

Wenn du eine generische Fehlermeldung erhalten hast, suche nach häufigen Fehlern.

  • Du verwendest nicht unterstützte Plug-Ins. Weitere Informationen findest du unter Informationen zu GitHub Pages und Jekyll.
  • Du hast die source-Einstellung in deiner Datei _config.yml geändert. Wenn du deine Website über einen Branch veröffentlichst, überschreibt GitHub Pages diese Einstellung während des Buildvorgangs.
  • Ein Dateiname in deinen veröffentlichten Dateien enthält einen Doppelpunkt (:). Dies wird nicht unterstützt.

Wenn du eine bestimmte Fehlermeldung erhalten hast, lies die nachfolgenden Informationen zur Fehlerbehebung für die jeweilige Fehlermeldung.

Nachdem du Fehler behoben hast, löse einen anderen Build aus, indem du die Änderungen an den Quellbranch deiner Website pushst (wenn die Veröffentlichung über einen Branch erfolgt) oder deinen benutzerdefinierten GitHub Actions-Workflow auslöst (wenn du die Veröffentlichung mit GitHub Actions vornimmst).

Fehler bei der Dateikonfiguration

Dieser Fehler bedeutet, dass deine Website nicht erstellt werden konnte, weil die Datei _config.yml Syntaxfehler enthält.

Stelle zur Problembehandlung sicher, dass deine _config.yml-Datei folgenden Regeln folgt:

  • Verwende Leerzeichen statt Tabs.
  • Füge nach dem : für jedes Schlüssel-Wert-Paar ein Leerzeichen ein. Beispiel: timezone: Africa/Nairobi.
  • Verwende nur UTF-8-Zeichen.
  • Setze Sonderzeichen wie : in Anführungszeichen. Beispiel: title: "my awesome site: an adventure in parse errors".
  • Verwende | in mehrzeiligen Werten, um neue Zeilen zu erstellen, und >, um neue Zeilen zu ignorieren.

Um eventuelle Fehler zu erkennen, kannst du den Inhalt deiner YAML-Datei in einen YAML-Linter wie YAML Validator kopieren und einfügen.

Note: If your repository contains symbolic links, you will need to publish your site using a GitHub Actions workflow. For more information about GitHub Actions, see "GitHub Actions-Dokumentation."

Datum besitzt ungültiges Datum/Uhrzeit

Dieser Fehler bedeutet, dass eine Seite der Website einen ungültigen Wert für Datum/Uhrzeit enthält.

Zur Fehlerbehebung prüfe die in der Fehlermeldung genannte Datei und deren Layouts auf Aufrufe datumsbezogener Liquid-Filter. Prüfe, ob alle Variablen, die an datumsabhängige Liquid-Filter übergeben werden, Werte enthalten und nicht nil oder "" übergeben. Weitere Informationen findest du in der Liquid-Dokumentation unter Liquid-Filter.

Datei ist im Verzeichnis „includes“ nicht vorhanden

Dieser Fehler bedeutet, dass dein Code auf eine Datei verweist, die sich nicht im Verzeichnis _includes befindet.

Zur Problembehandlung durchsuche die in der Fehlermeldung genannte Datei nach include, um festzustellen, ob du auf andere Dateien verwiesen hast, z. B. {% include example_header.html %}. Wenn sich eine der Dateien, auf die du verwiesen hast, nicht im Verzeichnis _includes befindet, kopiere oder verschiebe die Dateien in das Verzeichnis _includes.

Datei ist nicht ordnungsgemäß UTF-8-codiert

Dieser Fehler bedeutet, dass du nicht lateinische Buchstaben wie 日本語 verwendet hast, ohne dem Computer mitzuteilen, dass er diese Symbole erwarten soll.

Zur Problembehandlung erzwingst du die UTF-8-Kodierung, indem du die folgende Zeile deiner _config.yml-Datei hinzufügst:

encoding: UTF-8

Textmarkersprache ungültig

Dieser Fehler bedeutet, dass du andere Syntaxmarker als Rouge oder Pygments in deiner Konfigurationsdatei angegeben hast.

Zur Problembehandlung aktualisierst du deine _config.yml-Datei, um Rouge oder Pygments anzugeben. Weitere Informationen findest du unter Informationen zu GitHub Pages und Jekyll.

Ungültiges Beitragsdatum

Dieser Fehler bedeutet, dass ein Beitrag auf deiner Website ein ungültiges Datum im Dateinamen oder im YAML-Frontmatter enthält.

Zur Fehlerbehebung formatiere alle Datumsangaben als YYYY-MM-DD HH:MM:SS für UTC, und prüfe, ob gültige Kalenderdaten angegeben sind. Um eine Zeitzone mit einer Abweichung von UTC festzulegen, verwende das Format JJJJ-MM-TT hh:mm:ss +/- tttt, z. B. 2014-04-18 11:30:00 +0800.

Wenn du ein Datumsformat in deiner Datei _config.yml angibst, stelle sicher, dass das Format richtig ist.

Sass oder SCSS ungültig

Dieser Fehler bedeutet, dass dein Repository eine Sass- oder SCSS-Datei mit ungültigem Inhalt enthält.

Zur Fehlerbehebung prüfe die in der Fehlermeldung genannte Zeilennummer auf ungültige Sass oder SCSS. Damit solche Fehler in Zukunft vermieden werden, installiere einen Sass- oder SCSS-Linter für deinen meistgenutzten Text-Editor.

Ungültiges Submodul

Dieser Fehler bedeutet, dass dein Repository ein nicht ordnungsgemäß initialisiertes Submodul enthält.

Zur Fehlerbehebung entscheide zuerst, ob du tatsächlich ein Submodul verwenden möchtest, bei dem es sich um ein Git-Projekt innerhalb eines Git-Projekts handelt; Submodule werden manchmal versehentlich erstellt.

Wenn du kein Submodul verwenden möchtest, entferne das Submodul, und ersetze dabei PFAD-ZUM-SUBMODUL durch den Pfad zum Submodul:

git submodule deinit PATH-TO-SUBMODULE
git rm PATH-TO-SUBMODULE
git commit -m "Remove submodule"
rm -rf .git/modules/PATH-TO-SUBMODULE

Wenn du das Untermodul verwenden möchtest, stelle sicher, dass du beim Verweisen auf das Untermodul https:// (nicht http://) verwendest, und dass sich das Untermodul in einem öffentlichen Repository befindet.

Ungültige YAML in der Datendatei

Dieser Fehler bedeutet, dass eine der weiteren Dateien im _data-Ordner ungültige YAML-Dateien enthält.

Stelle zur Problembehandlung sicher, dass die YAML-Dateien in deinem _data-Ordner folgende Regeln erfüllen:

  • Verwende Leerzeichen statt Tabs.
  • Füge nach dem : für jedes Schlüssel-Wert-Paar ein Leerzeichen ein. Beispiel: timezone: Africa/Nairobi.
  • Verwende nur UTF-8-Zeichen.
  • Setze Sonderzeichen wie : in Anführungszeichen. Beispiel: title: "my awesome site: an adventure in parse errors".
  • Verwende | in mehrzeiligen Werten, um neue Zeilen zu erstellen, und >, um neue Zeilen zu ignorieren.

Um eventuelle Fehler zu erkennen, kannst du den Inhalt deiner YAML-Datei in einen YAML-Linter wie YAML Validator kopieren und einfügen.

Weitere Informationen zu Jekyll-Datendateien findest du in der Jekyll-Dokumentation unter Datendateien.

Markdown-Fehler

Dieser Fehler bedeutet, dass dein Repository Markdownfehler enthält.

Zur Fehlerbehebung verwende einen unterstützten Markdown-Prozessor. Weitere Informationen findest du unter Markdown-Prozessor für deine GitHub Pages-Website mit Jekyll festlegen.

Prüfe außerdem, ob die in der Fehlermeldung genannte Datei eine gültige Markdown-Syntax umfasst. Weitere Informationen findest du unter Markdown: Syntax auf Daring Fireball.

Dokumentordner fehlt

Dieser Fehler bedeutet, dass du den docs-Ordner in einem Branch als Veröffentlichungsquelle ausgewählt hast, aber es gibt in diesem Branch keinen docs-Ordner im Stamm deines Repositorys.

Wenn dein docs-Ordner versehentlich verschoben wurde, versuche zur Problembehandlung, den docs-Ordner zurück in den Stamm deines Repositorys auf dem Branch zu verschieben, den du für deine Veröffentlichungsquelle gewählt hast. Wenn der docs-Ordner versehentlich gelöscht wurde, kannst du entweder:

  • Mache den Löschvorgang mit Git rückgängig. Weitere Informationen findest du in der Git-Dokumentation unter git-revert.
  • Erstelle einen neuen docs-Ordner im Stamm deines Repositorys auf dem Branch, den du für die Veröffentlichungsquelle ausgewählt hast, und füge die Quelldateien deiner Website dem Ordner hinzu. Weitere Informationen findest du unter Neue Dateien erstellen.
  • Ändere die Veröffentlichungsquelle. Weitere Informationen findest du unter Eine Veröffentlichungsquelle für deine GitHub Pages-Website konfigurieren.

Submodul fehlt

Dieser Fehler bedeutet, dass dein Repository ein nicht vorhandenes oder ein nicht ordnungsgemäß initialisiertes Submodul enthält.

Zur Fehlerbehebung entscheide zuerst, ob du tatsächlich ein Submodul verwenden möchtest, bei dem es sich um ein Git-Projekt innerhalb eines Git-Projekts handelt; Submodule werden manchmal versehentlich erstellt.

Wenn du kein Submodul verwenden möchtest, entferne das Submodul, und ersetze dabei PFAD-ZUM-SUBMODUL durch den Pfad zum Submodul:

git submodule deinit PATH-TO-SUBMODULE
git rm PATH-TO-SUBMODULE
git commit -m "Remove submodule"
rm -rf .git/modules/PATH-TO-SUBMODULE

Soll ein Submodul verwendet werden, initialisiere das Submodul. Weitere Informationen findest du unter Git-Tools – Untermodule im Pro Git-Buch.

Dieser Fehler bedeutet, dass du relative Permalinks in der Datei _config.yml nutzt, die nicht von GitHub Pages unterstützt werden.

Permalinks sind permanente URLs, die auf einen bestimmten Beitrag oder eine bestimmte Seite deiner Website verweisen. Absolute Permalinks beginnen mit dem Root der Website, relative Permalinks dagegen mit dem Ordner, in dem sich die referenzierte Seite befindet. GitHub Pages und Jekyll unterstützen relative Permalinks nicht mehr. Weitere Informationen zu Permalinks findest du in der Jekyll-Dokumentation unter Permalinks.

Entferne zur Problembehandlung die relative_permalinks-Zeile aus der Datei _config.yml, und formatiere alle relativen Permalinks auf deiner Website in absolute Permalinks um. Weitere Informationen findest du unter Bearbeiten von Dateien.

Syntaxfehler in der „for“-Schleife

Dieser Fehler bedeutet, dass dein Code ungültige Syntax in einer Liquid-for-Schleifen-Deklaration enthält.

Vergewissere dich zur Problembehandlung, dass alle for-Schleifen in der in der Fehlermeldung erwähnten der Datei die richtige Syntax haben. Weitere Informationen zur richtigen Syntax für for-Schleifen findest du in der Liquid-Dokumentation unter Iterations-Tags.

Tag nicht ordnungsgemäß geschlossen

Diese Fehlermeldung bedeutet, dass dein Code ein logisches Tag enthält, das nicht korrekt geschlossen ist. {% capture example_variable %} muss z. B. von {% endcapture %} geschlossen werden.

Zur Fehlerbehebung prüfe, ob alle logischen Tags in der Datei, die in der Fehlermeldung genannt ist, ordnungsgemäß geschlossen sind. Weitere Informationen findest du in der Liquid-Dokumentation unter Liquid-Tags.

Tag nicht ordnungsgemäß beendet

Diese Fehlermeldung bedeutet, dass dein Code ein output-Tag enthält, das nicht korrekt beendet wurde. Beispiel: {{ page.title } anstelle von {{ page.title }}.

Vergewissere dich zur Problembehandlung, dass alle Ausgabe-Tags in der in der Fehlermeldung erwähnten Datei mit }} beendet werden. Weitere Informationen findest du in der Liquid-Dokumentation unter Liquid-Objekte.

Unbekannter Tag-Fehler

Dieser Fehler bedeutet, dass dein Code ein nicht erkanntes Liquid-Tag enthält.

Zur Fehlerbehebung prüfe, ob alle Liquid-Tags in der Datei, die in der Fehlermeldung genannt ist, den Jekyll-Standardvariablen entsprechen und ob die Tag-Namen korrekt geschrieben sind. Eine Liste der Standardvariablen findest du in der Jekyll-Dokumentation unter Variablen.

Nicht unterstützte Plug-ins sind häufig die Quelle für unbekannte Tags. Wenn du ein nicht unterstütztes Plug-in auf der Website verwendest, also die Website lokal erstellen und die statischen Dateien per Push-Verfahren an GitHub Enterprise Server übertragen, darf das Plug-in keine Tags umfassen, die nicht in den Jekyll-Standardvariablen aufgeführt sind. Eine Liste unterstützter Plug-Ins findest du unter Informationen zu GitHub Pages und Jekyll.