关于 GitHub Pages 和 Jekyll

关于 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 设置。

前页附属资料

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

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

主题

您可以将 Jekyll 主题添加到 GitHub Pages 站点，以自定义站点的外观。 更多信息请参阅 Jekyll 文档中的“主题”。

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

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

插件

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

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

• jekyll-coffeescript
• jekyll-default-layout
• jekyll-gist
• jekyll-github-metadata
• jekyll-optional-front-matter
• jekyll-paginate
• jekyll-readme-index
• jekyll-titles-from-headings
• jekyll-relative-links

您可以通过在 _config.yml 文件中添加插件的 gem 到 plugins 设置来启用额外的插件。 更多信息请参阅 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

本地构建网站

当更改合并到站点的发布源时，对站点的更改将自动发布。 如果想先预览您的更改，可以在本地而不是 GitHub Enterprise 上进行更改。 然后在本地测试站点。 更多信息请参阅“使用 Jekyll 在本地测试 GitHub Pages 站点”。