我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

关于 GitHub Pages 和 Jekyll

Jekyll 是一个静态站点生成器,内置 GitHub Pages 支持。

GitHub Pages 可用于具有 GitHub Free 的公共仓库,以及具有 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有仓库。

本文内容

关于 Jekyll

Jekyll 是一个静态站点生成器,内置 GitHub Pages 支持和简化的构建过程。 Jekyll 使用 Markdown 和 HTML 文件,并根据您选择的布局创建完整静态网站。 Jekyll 支持 Markdown 和 Lick,这是一种可在网站上加载动态内容的模板语言。 更多信息请参阅 Jekyll

Windows 并未正式支持 Jekyll。 更多信息请参阅 Jekyll 文档中的“Windows 上的 Jekyll”。

我们建议将 Jekyll 用于 GitHub Pages。 如果您喜欢,可以使用其他静态站点生成器或者在本地或其他服务器上自定义构建过程。 更多信息请参阅“关于 GitHub Pages”。

在 GitHub Pages 网站中配置 Jekyll

您可以通过编辑 _config.yml 文件来配置大多数 Jekyll 设置,例如网站的主题和插件。 更多信息请参阅 Jekyll 文档中的“配置”。

对于 GitHub Pages 站点,有些配置设置不能更改。

lsi: false
safe: true
source: [your repo's top level directory]
incremental: false
highlighter: rouge
gist:
  noscript: false
kramdown:
  math_engine: mathjax
  syntax_highlighter: rouge

默认情况下,Jekyll 不会构建以下文件或文件夹:

  • 位于文件夹 /node_modules/vendor
  • 开头为 _.,或 #
  • 结尾为 ~
  • 被配置文件中的 exclude 设置排除

如果您想要 Jekyll 处理其中任何文件,可以使用配置文件中的 includes 设置。

前页附属资料

To set variables and metadata, such as a title and layout, for a page or post on your site, you can add YAML front matter to the top of any Markdown or HTML file. For more information, see "Front Matter" in the Jekyll documentation.

您可以添加 site.github 到帖子或页面,以将任何仓库引用元数据添加到您的网站。 更多信息请参阅 Jekyll 元数据文档中的“使用site.github”。

主题

You can add a Jekyll theme to your GitHub Pages site to customize the look and feel of your site. 更多信息请参阅 Jekyll 文档中的“主题”。

您可以手动添加支持的主题到站点。 更多信息请参阅GitHub Pages 站点上 "支持的主题"和“使用 Jekyll 添加主题到 GitHub Pages 站点”。

您可以通过编辑主题文件来覆盖任何主题的默认值。 更多信息请参阅您的主题文档和 Jekyll 文档中的“覆盖主题默认值“。

插件

您可以下载或创建 Jekyll 插件,以便为您的网站扩展 Jekyll 的功能。 例如, jemoji 插件允许您在站点的任何页面上使用 GitHub 风格的表情符号,就像在 GitHub 上使用一样。 更多信息请参阅 Jekyll 文档中的“插件”。

GitHub Pages 使用默认启用且不能禁用的插件:

您可以通过在 _config.yml 文件中添加插件的 gem 到 plugins 设置来启用额外的插件。 更多信息请参阅 Jekyll 文档中的“配置”。 有关支持的插件列表,请参阅 GitHub Pages 网站上的“依赖项版本”。

有关特定插件的使用信息,请参阅插件的文档。

提示: 您可以保持更新 GitHub Pages gem,确保使用所有插件的最新版本。 更多信息请参阅 GitHub Pages 网站上的“使用 Jekyll 本地测试 GitHub Pages 站点”和“依赖项版本”。

GitHub Pages 无法使用不支持的插件构建网站。 如果想使用不支持的插件,请在本地生成网站,然后将网站的静态文件推送到 GitHub Enterprise。

语法突显

为了使网站更容易读取,代码片段在 GitHub Pages 上突显,就像在 GitHub Enterprise 上突显一样。 有关在 GitHub Enterprise 上突显语法的更多信息,请参阅“创建和突显代码块”。

默认情况下,网站上的代码块将被 Jekyll 突出显示。 Jekyll 使用 Rouge 突显工具,它兼容于 Pygments。 如果在 _config.yml 文件中指定 Pygments,将改用 Rouge。 Jekyll 不能使用任何其他语法突显工具,如果您在 _config.yml 文件中指定其他语法突显工具,将会收到页面构建警告。 更多信息请参阅“关于 GitHub Pages 站点的 Jekyll 构建错误”。

如果想使用其他突显工具,如 highlight.js,则必须更新项目的 _config.yml 文件来禁用 Jekyll 的语法突显。

kramdown:
  syntax_highlighter_opts:
    disable : true

如果您的主题不含用于语法突显的 CSS,可以生成 GitHub 的语法突显 CSS 并将其添加到项目的 style.css 文件。

$ rougify style github > style.css

本地构建网站

Changes to your site are published automatically when the changes are merged into your site's publishing source. If you want to preview your changes first, you can make the changes locally instead of on GitHub Enterprise. Then, test your site locally. For more information, see "Testing your GitHub Pages site locally with Jekyll."

问问别人

找不到要找的内容?

联系我们