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.

In diesem Artikel

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.
  • Sie haben die source-Einstellung in Ihrer Datei _config.yml geändert. Wenn Sie Ihre Website von einer Verzweigung aus veröffentlichen, setzt GitHub Pages diese Einstellung während des Build-Prozesses außer Kraft.
  • 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 Sie alle Fehler behoben haben, lösen Sie einen weiteren Build aus, indem Sie die Änderungen in die Quellverzweigung Ihrer Website pushen (wenn Sie von einer Verzweigung aus veröffentlichen) oder indem Sie Ihren benutzerdefinierten Workflow GitHub Actions auslösen (wenn Sie mit GitHub Actions veröffentlichen).

Fehler bei der Dateikonfiguration

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

Stellen Sie zur Problembehandlung sicher, dass die Datei _config.yml folgenden Regeln entspricht:

  • 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 der 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 Dateien, auf die Sie verwiesen haben, nicht im Verzeichnis _includes befinden, kopieren oder verschieben Sie 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 erzwingen Sie die UTF-8-Kodierung, indem Sie der Datei _config.yml die folgende Zeile hinzufügen:

encoding: UTF-8

Textmarkersprache ungültig

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

Zur Problembehandlung aktualisieren Sie die Datei _config.yml, 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.

Stellen Sie bei Angabe eines Datumsformats in der Datei _config.yml 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 in der Datei _config.yml relative Permalinks vorliegen, die von GitHub Pages nicht 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.

Entfernen Sie zur Problembehandlung die Zeile relative_permalinks aus der Datei _config.yml, und formatieren Sie alle relativen Permalinks auf Ihrer Site 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.