关于 GitHub Pages 与 Jekyll - GitHub 文档

注意

虽然 github-pages gem 在某些工作流中仍受支持，但现在推荐使用 GitHub Actions 来部署和自动化 GitHub Pages 站点。

关于 Jekyll

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

Jekyll 官方不支持 Windows。更多信息，请参阅 Jekyll 文档中的 Jekyll on Windows。

我们建议在 GitHub Pages 上使用 Jekyll。如果您愿意，也可以使用其他静态站点生成器，或在本地或其他服务器上自定义构建流程。更多信息，请参阅创建 GitHub Pages 站点。

在 GitHub Pages 站点中配置 Jekyll

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

某些配置设置在 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 处理上述任意文件，可以在配置文件中使用 include 设置。

Front matter（页面前置数据）

要为页面或文章设置变量和元数据（例如标题和布局），可以在任意 Markdown 或 HTML 文件顶部添加 YAML front matter。更多信息，请参阅 Jekyll 文档中的 Front Matter（页面前置数据）。

您可以在文章或页面中使用 site.github 来添加仓库引用元数据。更多信息，请参阅 Jekyll 元数据文档中的 Using site.github。

Themes

您可以为 GitHub Pages 站点添加 Jekyll 主题，以自定义站点的外观和体验。更多信息，请参阅 Jekyll 文档中的 Themes（主题）。

您可以在 GitHub 上为站点添加受支持的主题。更多信息，请参阅 GitHub Pages 站点中的 Supported themes（受支持的主题），以及 Adding a theme to your GitHub Pages site using Jekyll（使用 Jekyll 为 GitHub Pages 站点添加主题）。

要使用托管在 GitHub 上的其他开源 Jekyll 主题，您可以手动添加该主题。更多信息，请参阅 GitHub 上托管的主题与使用 Jekyll 为 GitHub Pages 站点添加主题。

您可以通过编辑主题文件来覆盖主题的默认设置。更多信息，请查阅主题文档以及 Jekyll 文档中的 Overriding your theme's defaults（覆盖主题默认值）。

Plugins

您可以下载或创建 Jekyll 插件，以扩展站点的功能。例如，jemoji 插件可以让您在站点的任意页面中像在 GitHub 上一样使用 GitHub 风格的表情符号。更多信息，请参阅 Jekyll 文档中的 Plugins（插件）。

GitHub Pages 使用默认启用且无法禁用的插件：

您可以通过在 _config.yml 文件的 plugins 设置中添加插件的 gem 来启用额外插件。更多信息，请参阅 Jekyll 文档中的 Configuration（配置）。

有关受支持插件的列表，请参阅 GitHub Pages 站点上的 Dependency versions（依赖版本）。有关特定插件的使用信息，请查阅该插件的文档。

提示

通过保持 GitHub Pages gem 为最新版本，您可以确保所有插件都是最新的。更多信息，请参阅使用 Jekyll 本地测试 GitHub Pages 站点以及 GitHub Pages 站点上的 Dependency versions（依赖版本）。

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

Syntax highlighting（语法高亮）

为提升站点可读性，GitHub Pages 会对代码片段进行高亮显示，方式与 GitHub 上的代码高亮相同。有关语法高亮的更多信息，请参阅 Creating and highlighting code blocks（创建和高亮代码块）。

默认情况下，站点上的代码块会由 Jekyll 使用 Rouge 高亮器（兼容 Pygments）进行高亮。如果您在 _config.yml 文件中指定了 Pygments，Rouge 将作为回退使用。Jekyll 不能使用其他语法高亮器；如果在 _config.yml 中指定了其它高亮器，将会收到页面构建警告。更多信息，请参阅 About Jekyll build errors for GitHub Pages sites（关于 GitHub Pages 站点的 Jekyll 构建错误）。

注意

Rouge 只识别小写的语言标识符用于围栏代码块。支持的语言列表请参阅 Languages（语言列表）。

如果想使用其他高亮器，例如 highlight.js，必须通过更新项目的 _config.yml 文件来禁用 Jekyll 的语法高亮。

kramdown:
  syntax_highlighter_opts:
    disable : true

如果您的主题未包含语法高亮的 CSS，您可以生成 GitHub 的语法高亮 CSS 并将其添加到项目的 style.css 文件中。

rougify style github > style.css

在本地构建站点

如果您从分支发布，当更改合并到站点的发布源时，站点的更改会自动发布。若您使用自定义 GitHub Actions 工作流发布，只要工作流被触发（通常是对默认分支的推送），更改就会发布。若您想先预览更改，可以在本地而非 GitHub 上进行更改，然后在本地测试站点。欲了解更多信息，请参阅在本地使用 Jekyll 测试您的 GitHub Pages 站点。

关于 GitHub Pages 和 Jekyll

谁可以使用此功能？

本文内容