关于 GitHub Pages 和 Jekyll

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

谁可以使用此功能？

GitHub Pages 可用于使用 GitHub Free 和 GitHub Free for organizations 的公共仓库，以及使用 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有仓库。有关更多信息，请参阅“GitHub 的计划”。

从 2024 年 6 月 30 日起，所有 GitHub Pages 构建都将使用 GitHub Actions。无需进行其他更改，但必须在您的仓库中启用 GitHub Actions 才能继续构建。有关启用 GitHub Actions 的更多信息，请参阅“管理仓库的 GitHub Actions 设置”。

本文内容

关于 Jekyll

Jekyll 是一个静态网站生成器，内置支持 GitHub Pages 和简化的构建流程。Jekyll 使用 Markdown 和 HTML 文件，根据您选择的布局创建完整的静态网站。Jekyll 支持 Markdown 和 Liquid，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 设置。

前置内容

要为网站上的页面或帖子设置变量和元数据（例如标题和布局），您可以在任何 Markdown 或 HTML 文件的顶部添加 YAML 前置内容。有关更多信息，请参阅 Jekyll 文档中的“前置内容”。

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

主题

您可以将 Jekyll 主题添加到您的 GitHub Pages 网站，以自定义网站的外观和感觉。有关更多信息，请参阅 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 更新来确保使用所有插件的最新版本。有关更多信息，请参阅 GitHub Pages 网站上的“使用 Jekyll 在本地测试您的 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 网站”。