文章版本: Enterprise Server 2.17
Troubleshooting Jekyll build errors for GitHub Pages sites
You can use Jekyll build error messages to troubleshoot problems with your GitHub Pages site.
GitHub Pages 适用于具有 GitHub Free 和组织的 GitHub Free 的公共仓库,以及具有 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有仓库。
本文内容
- Troubleshooting build errors
- Config file error
- Date is not a valid datetime
- File does not exist in includes directory
- File is a symlink
- File is not properly UTF-8 encoded
- Invalid highlighter language
- Invalid post date
- Invalid Sass or SCSS
- Invalid submodule
- Invalid YAML in data file
- Markdown errors
- Missing docs folder
- Missing submodule
- Relative permalinks configured
- Symlink does not exist within your site's repository
- Syntax error in 'for' loop
- Tag not properly closed
- Tag not properly terminated
- Unknown tag error
Troubleshooting build errors
If Jekyll encounters an error building your GitHub Pages site locally or on GitHub Enterprise, you can use error messages to troubleshoot. For more information about error messages and how to view them, see "About Jekyll build errors for GitHub Pages sites."
If you received a generic error message, check for common issues.
- You're using unsupported plugins. For more information, see "About GitHub Pages and Jekyll."
- You changed the
source
setting in your _config.yml file. GitHub Pages overrides this setting during the build process. - A filename in your publishing source contains a colon (
:
) which is not supported.
If you received a specific error message, review the troubleshooting information for the error message below.
After you've fixed any errors, push the changes to your site's publishing source to trigger another build on GitHub Enterprise.
Config file error
This error means that your site failed to build because the _config.yml file contains syntax errors.
To troubleshoot, make sure that your _config.yml file follows these rules:
- 使用空格代替制表符。
- 对每个键值对在
:
后包含一个空格,如timezone: Africa/Nairobi
。 - 仅使用 UTF-8 字符。
- 引用
:
等特殊字符,如title: "my awesome site: an adventure in parse errors"
。 - 对于多行值,请使用
|
创建换行符,使用>
忽略换行符。
为识别任何错误,可以将 YAML 文件的内容复制并粘贴到 YAML 语法检查,如 YAML 验证器。
Date is not a valid datetime
This error means that one of the pages on your site includes an invalid datetime.
To troubleshoot, search the file in the error message and the file's layouts for calls to any date-related Liquid filters. Make sure that any variables passed into date-related Liquid filters have values in all cases and never pass nil
or ""
. For more information, see "Liquid filters" in the Liquid documentation.
File does not exist in includes directory
This error means that your code references a file that doesn't exist in your _includes directory.
要进行故障排除,请在 include
的错误消息中搜索文件,以查看您在哪些地方引用了其他文件, 例如 {% include example_header.html %}
。 If any of the files you've referenced aren't in the _includes directory, copy or move the files into the _includes directory.
File is a symlink
This error means that your code references a symlinked file that does not exist in the publishing source for your site.
要进行故障排除,请在 include
的错误消息中搜索文件,以查看您在哪些地方引用了其他文件, 例如 {% include example_header.html %}
。 If any of the files you've referenced are symlinked, copy or move the files into the _includes directory.
File is not properly UTF-8 encoded
This error means that you used non-Latin characters, like 日本語
, without telling the computer to expect these symbols.
To troubleshoot, force UTF-8 encoding by adding the following line to your _config.yml file:
encoding: UTF-8
Invalid highlighter language
This error means that you specified any syntax highlighter other than Rouge or Pygments in your configuration file.
To troubleshoot, update your _config.yml file to specify Rouge or Pygments. For more information, see "About GitHub Enterprise and Jekyll."
Invalid post date
This error means that a post on your site contains an invalid date in the filename or YAML front matter.
To troubleshoot, make sure all dates are formatted as YYYY-MM-DD HH:MM:SS for UTC and are actual calendar dates. To specify a time zone with an offset from UTC, use the format YYYY-MM-DD HH:MM:SS +/-TTTT, like 2014-04-18 11:30:00 +0800
.
If you specify a date format in your _config.yml file, make sure the format is correct.
Invalid Sass or SCSS
This error means your repository contains a Sass or SCSS file with invalid content.
To troubleshoot, review the line number included in the error message for invalid Sass or SCSS. To help prevent future errors, install a Sass or SCSS linter for your favorite text editor.
Invalid submodule
This error means that your repository includes a submodule that hasn't been properly initialized.
要排除故障,请先决定您是否真的想要使用子模块,它是 Git 项目内的 Git 项目; 子模块有时是意外创建的。
如果不想使用子模块,请删除子模块,用子模块的路径替换 PATH TO-SUBMODULE:
$ git submodule deinit PATH-TO-SUBMODULE
$ git rm PATH-TO-SUBMODULE
$ git commit -m "Remove submodule"
$ rm -rf .git/modules/PATH-TO-SUBMODULE
If do you want to use the submodule, make sure you use https://
when referencing the submodule (not http://
) and that the submodule is in a public repository.
Invalid YAML in data file
This error means that one of more files in the _data folder contains invalid YAML.
To troubleshoot, make sure the YAML files in your _data folder follow these rules:
- 使用空格代替制表符。
- 对每个键值对在
:
后包含一个空格,如timezone: Africa/Nairobi
。 - 仅使用 UTF-8 字符。
- 引用
:
等特殊字符,如title: "my awesome site: an adventure in parse errors"
。 - 对于多行值,请使用
|
创建换行符,使用>
忽略换行符。
为识别任何错误,可以将 YAML 文件的内容复制并粘贴到 YAML 语法检查,如 YAML 验证器。
For more information about Jekyll data files, see "Data Files" in the Jekyll documentation.
Markdown errors
This error means that your repository contains Markdown errors.
To troubleshoot, make sure you are using a supported Markdown processor. For more information, see "Setting a Markdown processor for your GitHub Pages site using Jekyll."
Then, make sure the file in the error message uses valid Markdown syntax. For more information, see "Markdown: Syntax" on Daring Fireball.
Missing docs folder
This error means that you have chosen the docs
folder as your publishing source, but there is no docs
folder in the root of your repository on the master
branch.
To troubleshoot, if your docs
folder was accidentally moved, try moving the docs
folder back to the root of your repository on the master
branch. If the docs
folder was accidentally deleted, you can either:
- Use Git to revert or undo the deletion. For more information, see "git-revert" in the Git documentation.
- Create a new
docs
folder in the root of your repository on themaster
branch and add your site's source files to the folder. 更多信息请参阅“创建新文件”。 - Change your publishing source. 更多信息请参阅“配置 GitHub Pages 的发布源”。
Missing submodule
This error means that your repository includes a submodule that doesn't exist or hasn't been properly initialized.
要排除故障,请先决定您是否真的想要使用子模块,它是 Git 项目内的 Git 项目; 子模块有时是意外创建的。
如果不想使用子模块,请删除子模块,用子模块的路径替换 PATH TO-SUBMODULE:
$ git submodule deinit PATH-TO-SUBMODULE
$ git rm PATH-TO-SUBMODULE
$ git commit -m "Remove submodule"
$ rm -rf .git/modules/PATH-TO-SUBMODULE
If you do want to use a submodule, initialize the submodule. For more information, see "Git Tools - Submodules" in the Pro Git book.
Relative permalinks configured
This errors means that you have relative permalinks, which are not supported by GitHub Pages, in your _config.yml file.
Permalinks are permanent URLs that reference a particular page on your site. Absolute permalinks begin with the root of the site, while relative permalinks begin with the folder containing the referenced page. GitHub Pages 和 Jekyll 不再支持相对永久链接。 For more information about permalinks, see "Permalinks" in the Jekyll documentation.
To troubleshoot, remove the relative_permalinks
line from your _config.yml file and reformat any relative permalinks in your site with absolute permalinks. For more information, see "Editing files in your repository."
Symlink does not exist within your site's repository
This error means that your site includes a symbolic link (symlink) that does not exist in the publishing source for your site. For more information about symlinks, see "Symbolic link" on Wikipedia.
To troubleshoot, determine if the file in the error message is used to build your site. If not, or if you don't want the file to be a symlink, delete the file. If the symlinked file is necessary to build your site, make sure the file or directory the symlink references is in the publishing source for your site. To include external assets, consider using a third-party package manager such as Bower.
Syntax error in 'for' loop
This error means that your code includes invalid syntax in a Liquid for
loop declaration.
To troubleshoot, make sure all for
loops in the file in the error message have proper syntax. For more information about proper syntax for for
loops, see "Iteration tags" in the Liquid documentation.
Tag not properly closed
This error message means that your code includes a logic tag that is not properly closed. For example, {% capture example_variable %}
must be closed by {% endcapture %}
.
To troubleshoot, make sure all logic tags in the file in the error message are properly closed. For more information, see "Liquid tags" in the Liquid documentation.
Tag not properly terminated
This error means that your code includes an output tag that is not properly terminated. For example, {{ page.title }
instead of {{ page.title }}
.
To troubleshoot, make sure all output tags in the file in the error message are terminated with }}
. For more information, see "Liquid objects" in the Liquid documentation.
Unknown tag error
This error means that your code contains an unrecognized Liquid tag.
To troubleshoot, make sure all Liquid tags in the file in the error message match Jekyll's default variables and there are no typos in the tag names. For a list of default varibles, see "Variables" in the Jekyll documentation.
Unsupported plugins are a common source of unrecognized tags. If you use an unsupported plugin in your site by generating your site locally and pushing your static files to GitHub Enterprise, make sure the plugin is not introducing tags that are not in Jekyll's default variables. For a list of supported plugins, see "About GitHub Pages and Jekyll."