关于 GitHub Pages 和 Jekyll

Jekyll 是一款静态网站生成器，内置支持 GitHub Pages。

谁可以使用此功能？

GitHub Pages 可用于包含 GitHub 免费版和 GitHub 免费组织版项目的公共仓库，以及包含 GitHub 专业版、GitHub 团队版、GitHub Enterprise Cloud 和 GitHub Enterprise Server 项目的公共和私有仓库。有关详细信息，请参阅“GitHub 的套餐”。

GitHub Pages 现在使用 GitHub Actions 来执行 Jekyll 构建。当使用分支作为构建的来源时，如果要使用内置 Jekyll 工作流，则必须在您的仓库中启用 GitHub Actions。或者，如果 GitHub Actions 不可用或已禁用，则向源分支的根目录添加 `.nojekyll` 文件将绕过 Jekyll 构建过程并直接部署内容。有关启用 GitHub Actions 的更多信息，请参阅“管理仓库的 GitHub Actions 设置”。

本文内容

关于 Jekyll

Jekyll 是一款静态网站生成器，内置支持 GitHub Pages，并简化了构建流程。Jekyll 使用 Markdown 和 HTML 文件，并根据您选择的布局创建完整的静态网站。Jekyll 支持 Markdown 和 Liquid（一种在您的站点上加载动态内容的模板语言）。有关详细信息，请参阅 Jekyll。

Jekyll 不正式支持 Windows。有关详细信息，请参阅 Jekyll 文档中的“Jekyll on Windows”。

我们建议将 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 处理任何这些文件，可以在配置文件中使用 `include` 设置。

前置 matter

要设置变量和元数据（例如站点的标题和布局），可以在任何 Markdown 或 HTML 文件的顶部添加 YAML 前置 matter。有关详细信息，请参阅 Jekyll 文档中的“前置 Matter”。

您可以将 `site.github` 添加到文章或页面中，以便将任何仓库引用元数据添加到您的站点。有关详细信息，请参阅 Jekyll 元数据文档中的“使用 `site.github`”。

主题

您可以向 GitHub Pages 站点添加 Jekyll 主题，以自定义站点的外观和风格。有关详细信息，请参阅 Jekyll 文档中的“主题”。

您可以向 GitHub 上的站点添加受支持的主题。有关详细信息，请参阅 GitHub Pages 站点上的“受支持的主题”和“使用 Jekyll 向 GitHub Pages 站点添加主题”。

要使用 GitHub 上托管的任何其他开源 Jekyll 主题，您可以手动添加该主题。有关详细信息，请参阅 GitHub 上托管的主题 和“使用 Jekyll 向 GitHub Pages 站点添加主题”。

您可以通过编辑主题文件来覆盖任何主题的默认值。有关详细信息，请参阅您的主题文档和 Jekyll 文档中的“覆盖主题的默认值”。

插件

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

GitHub Pages 使用默认启用的插件，这些插件无法禁用。

您可以通过将插件的 gem 添加到 `_config.yml` 文件中的 `plugins` 设置来启用其他插件。有关详细信息，请参阅 Jekyll 文档中的“配置”。

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

提示

您可以通过保持 GitHub Pages gem 更新来确保您使用的是所有插件的最新版本。有关详细信息，请参阅“使用 Jekyll 在本地测试 GitHub Pages 站点”和 GitHub Pages 站点上的“依赖项版本”。

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

语法高亮

为了使您的站点更易于阅读，代码片段在 GitHub Pages 站点上的高亮显示方式与在 GitHub 上一样。有关 GitHub 上语法高亮显示的更多信息，请参阅“创建和高亮显示代码块”。

默认情况下，站点上的代码块将由 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

在本地构建您的站点

如果您是从分支发布的，则当更改合并到站点的发布源时，对站点的更改会自动发布。如果您是从自定义 GitHub Actions 工作流发布的，则每当触发您的工作流时（通常是推送到默认分支时），更改都会发布。如果要先预览您的更改，则可以在本地而不是在 GitHub 上进行更改。然后，在本地测试您的站点。有关详细信息，请参阅“使用 Jekyll 在本地测试 GitHub Pages 站点”。