Jekyll 入门：一款免费开源的静态站点生成器

Jekyll 是一款免费且开源的静态站点生成器。与内容管理系统（例如 Drupal 和 WordPress）类似，Jekyll 可用于构建具有丰富且易于使用的导航的网站。然而，与 Drupal 和 WordPress 不同，Jekyll 一次性生成所有内容，而不是等待用户访问您网站的页面。

这种模式非常适合开源项目的网站，因为它重用了源代码中已使用的概念，例如版本控制。当然，主要的缺点是您的站点将完全缺乏动态功能。这些功能包括特定于每位访问者的“推荐”、用户评论或精美的管理界面；对于每位用户，站点的内容将是相同的。另一方面，静态站点本质上更安全，因为 Jekyll 在您的机器上运行，并且不会暴露给来自互联网的恶意行为者。服务器上的设置也将很简单。

Jekyll 在 2016 年 2 月的 Opensource.com 上被专题报道（《使用 Markdown 和 Jekyll 撰写博客的 6 个理由》）。我最近使用它为 QEMU 创建了一个网站，QEMU 是我在 Red Hat 工作的开源项目之一。在本文中，我将为首次使用 Jekyll 的用户提供技巧，引导读者创建新的 Jekyll 网站，并介绍 Jekyll 的主题和自定义功能。

入门

安装 Jekyll 最简单的方法是通过 RubyGems。RubyGems 适用于大多数 GNU/Linux 发行版；例如，在 Fedora 上，您可以使用 dnf install rubygems 安装它。

安装 RubyGems 后，以下步骤将安装 Jekyll 并在 test/ 目录中为新的 Jekyll 站点创建支架

gem install jekyll
jekyll new test

目录内容将如下所示

-rw-r--r--. 1 pbonzini pbonzini  525 15 mar 11.50 about.md
-rw-r--r--. 1 pbonzini pbonzini 1402 15 mar 11.50 _config.yml
-rw-rw-r--. 1 pbonzini pbonzini  953 15 mar 11.50 Gemfile
-rw-rw-r--. 1 pbonzini pbonzini 1180 15 mar 11.51 Gemfile.lock
-rw-r--r--. 1 pbonzini pbonzini  213 15 mar 11.50 index.md
drwxrwxr-x. 2 pbonzini pbonzini   50 15 mar 11.50 _posts/

两个 .md 文件是网站页面的源代码。您可以创建任意数量的目录，Jekyll 将扫描它们以查找 .md 和 .html 文件。其他 Markdown 文件位于 _posts 目录中；它们被处理以提供博客特有的功能，例如帖子日期和类别。

每个源文件都包含一个前言，描述页面的特征，后跟 Markdown 或 HTML 格式的页面内容。以下是 about.md 的开头

---
layout: page
title: About
permalink: /about/
---

This is the base Jekyll theme. [...]

--- 之间的所有内容都是前言。它以 YAML 编写，YAML 是一种人类可读的格式，Jekyll 使用它来处理结构化数据。前言很少或几乎不使用花哨的 YAML 功能。

为了生成页面，Jekyll 从主题模板（在本例中为“page”布局）中获取布局，并将其与前言中的数据和页面内容合并。前言还告诉 Jekyll 将结果放在哪里（在本例中为 /about/index.html）。

现在进入该目录，键入 bundle exec jekyll serve（如果您在多个网站上工作，bundle exec 确保您使用正确版本的 Jekyll），并将您的 Web 浏览器指向 http://127.0.0.1:4000/。您将看到这个

^{使用 “jekyll new” 创建的示例站点，如 Mozilla Firefox 所示。}

您的网站已转换为 HTML，结果放在 _site/ 目录中

drwxrwxr-x. 2 pbonzini pbonzini   23 15 mar 11.54 about/
drwxrwxr-x. 2 pbonzini pbonzini   21 15 mar 11.54 assets/
-rw-rw-r--. 1 pbonzini pbonzini 3836 15 mar 11.54 feed.xml
-rw-rw-r--. 1 pbonzini pbonzini 5301 15 mar 11.54 index.html
drwxrwxr-x. 3 pbonzini pbonzini   19 15 mar 11.54 jekyll/

本文不涵盖通过 Web 服务器部署 Jekyll。然而，值得一提的是，Jekyll 也是 GitHub “pages” 功能背后的引擎；将 GitHub 项目命名为“example.github.io” 就足以让您的静态站点生成并在 http://example.github.io/ 发布。然而，在这种情况下，您将失去使用非标准插件自定义网站的能力。

配置

在 jekyll init 创建的文件中，有 _config.yml，它为 Jekyll 提供全局配置。与前言一样，此文件采用 YAML 格式。

Jekyll 文档 详细解释了各种设置。默认值通常很好；根据我的经验，我主要使用 _config.yml 来自定义插件的操作，我将在本文后面讨论插件。一个例外是 permalink 选项的默认值，它是

permalink: /:categories/:year/:month/:day/:title.html

如果您注意到生成的网站中的 jekyll/ 目录，那就是它的来源！示例网站包含一个示例博客帖子，而 jekyll 只是其中一个类别。

我认为这是一个相当奇怪的 permalink 格式；幸运的是，更改它就像在 _config.yml 中添加一行一样简单

permalink: /blog/:year/:month/:day/:title/

主题

可悲的是，许多开源项目的网站看起来像是上次更新是在 20 世纪 90 年代，只是没有 “正在建设中” 的 GIF 动画。通常，问题仅仅是作者缺乏设计师经验。如果您的情形如此，您可能应该寻找一个好的免费模板并使其适应您的需求。jekyllthemes.org 提供了许多示例主题供您开始使用。许多主题托管在 GitHub 上，并且已经有一个 Gemfile；在这种情况下，您可以克隆存储库并立即开始使用它们

git clone https://github.com/daviddarnes/alembic jekylltest2
cd jekylltest2
bundle install
bundle exec jekyll serve

如果您选择的主题没有 Gemfile，您可以直接使用 jekyll serve，而无需通过 bundle，但将来可能会遇到向后兼容性问题。创建您自己的 Gemfile 更好，并且可以像这样简单

source "https://rubygems.org.cn"
ruby RUBY_VERSION
gem "jekyll"
group :jekyll_plugins do
   gem "jekyll-feed", "~> 0.6"
end

您自己的主题

许多网站提供以免费 Creative Commons 许可发布的 CSS 和 HTML5 模板，可以免费使用。两个示例是 TEMPLATED 和 HTML5 UP!，它们提供了数百个响应式主题，每个主题至少包含一个主页和一个二级页面。对于 QEMU 的网站，我从他们的 Linear 模板开始，尽管结果看起来完全不像。

您找到的并非所有主题都适合博客——另一方面，您可能不会使用 Jekyll 的博客功能——因此请确保您的模板与您网站中需要的功能良好匹配。例如，如果您要将 Jekyll 用于博客，您可能应该将自己限制在具有可选侧边栏的模板。侧边栏可用于链接每月或每类别存档。

请确保提前检查模板的要求。例如，TEMPLATED 和 HTML5 UP! 的主题的一个有争议的方面是它们使用 JavaScript 来提供响应式行为甚至页面样式。您的一些访问者可能会禁用 JavaScript，即使他们不禁用，访问者也可能会在浏览器加载 JavaScript 时看到未样式化内容的 “闪烁”。在我的例子中，我删除了这个库，并将其替换为简单的 CSS 文件，而没有牺牲页面的响应性。CSS 使为 “移动” 和 “桌面” 查看器轻松拥有单独的样式表，并且仅为移动用户添加菜单按钮只需要十几行 JavaScript 代码。如果您不想做这类工作，请提前检查模板的要求。

因为您将使用文本编辑器编辑 Jekyll 页面和布局，所以您还应确保您的模板具有可读的 HTML 和 CSS；一些设计师在他们的演示中使用 “精简” 的 HTML 和 CSS 代码，并且仅对收费提供实际源代码。

从 jekyll new 创建的支架开始，您可以将主题的源代码直接添加到 Jekyll 源代码目录中。如前所述，Jekyll 的模板系统通过定义多个布局来工作，这些布局存储在 _layouts/ 目录中。QEMU 网站有 三个主要布局，这非常典型

• home 用于主页，
• page 用于网站页面（没有侧边栏），
• blog 用于博客页面（带有侧边栏）。

博客布局进一步细分为 博客帖子 和 存档页面 的布局。

HTML 源代码的大部分可以由不同的布局共享。使用 Jekyll 的模板系统来避免重复，并将这些公共元素放在 _includes/ 目录中的单独文件中。所有 HTML 标头，其中包含指向 CSS 和 JavaScript 库的链接、导航菜单 和 站点地图、版权声明 以及 博客侧边栏 都可以通过这种方式提取出来。

如果您单击了链接，您会注意到文件中有更高级的内容，例如模板指令。别担心；您可以轻松地从 CSS/HTML 模板中的占位符内容开始。大多数 Jekyll 模板以类似的方式组织它们的 _includes 目录，并且从标准 Jekyll 模板、其他教程或 QEMU 网站合并这些高级元素将非常容易。

高级功能

到目前为止，我所介绍的内容应该足以构建一个功能性网站，该网站对于您的项目来说是独一无二的。然而，Jekyll 提供了更多功能，可以使您的网站更好，并简化您的工作。对于 QEMU 网站，我使用了两个功能：插件和集合。

插件

Jekyll 的插件系统提供了在站点生成时运行自定义 Ruby 代码的钩子。插件有几种类型，最常见的是生成器和标签。

许多插件以 Ruby gem 的形式存在；Jekyll 文档再次 解释了 如何将 gem 添加到您的 Gemfile 并使用 bundle 安装它们。jekyll new 已经配置了 jekyll-feed gem；jekyll-feed 是一个生成器插件，它以 Atom 格式生成博客帖子的 Feed。

然而，有时，现有的 gem 并不能完全满足您的需求。在这种情况下，您的网站可以使用自定义插件。

示例插件：博客存档

生成器插件允许您向 Jekyll 的输出添加目录和文件。它们的 Ruby 代码定义了 Jekyll 的 Generator 类的子类，以及一个可以生成任意数量输出文件的 generate。例如，生成器子类可以查看网站中的所有帖子，按月份对它们进行分组，并为每个月生成一个存档页面。

实际上，这正是 每月存档 插件所做的事情。QEMU 使用此插件并从博客的侧边栏链接到每月存档。另一个类似的插件生成基于类别的存档页面，这些页面链接在每个博客帖子的底部。

这些插件是高度可定制的。我之前提到过，存档的布局在一个单独的文件中，位于 _layouts/ 目录中。_config.yml 告诉插件要使用哪个布局以及如何格式化 URL

monthly_archive: {
  path: 'blog', layout: 'archive'
}
category_archive: {
  path: 'blog/category', layout: 'archive', slugify: true
}

示例插件：MarkDown includes

除了生成页面外，插件还可以用于向 Jekyll 的模板系统添加新命令。QEMU 网站使用其中一个插件来简化其 页面，这可以说是该网站中最复杂的页面。

此页面有一个水平菜单，可让您选择要显示的四个窗格中的哪一个。该菜单是使用 HTML 和 JavaScript 实现的，其代码 相当长。保持窗格的内容分开是可取的，并且，当我在做这件事时，我认为使用 Markdown 而不是 HTML 编写它会很好。奇怪的是，Jekyll 的 include 和 include_relative 指令仅允许您包含 HTML。在我的例子中，我想要类似于 include_relative（它包含来自当前目录而不是 _includes/ 的文件）的东西，但具有 Markdown 支持。

解决方案 只有 20 行代码；整个插件都放在一个文件中，您可以将其放入 _plugins/ 目录中。它提供了两个新的模板指令——markdown 和 markdown_relative——后者正是我所需要的。

集合

Jekyll 的另一个有趣功能是集合。集合有助于在您的网站中包含结构化数据——通过将数据与其表示形式分离，它们使任务更容易且更不容易出错。

集合数据存储在 _data 子目录中，并以 YAML 格式格式化，如下所示

- name: Paolo
  birthday: March 17
- name: Luisa
  birthday: November 28

如果以上四行存储在 _data/birthdays.yml 中，则模板将能够将其作为 site.data.birthdays 访问。以下 Liquid 代码

{% for person in site.data.birthdays %}
<p>{{person.name}}'s birthday is on {{person.birthday}}.</p>
{% endfor %}

将转换为

<p>Paolo's birthday is on March 17.</p>
<p>Luisa's birthday is on November 28.</p>

我在 QEMU 的网站中使用集合来表示我们的 发行版 和主页图库的 屏幕截图。在这两种情况下，表示形式都在 include 文件中进一步抽象，例如 这个用于发行版的文件。发行版集合特别有用；QEMU 发行过程很长，而漂亮的 YAML 格式最大限度地减少了更新网站的负担。

结论

使用 Jekyll 构建 QEMU 的新网站真的很有趣。我大约用了一天的时间就构建了网站的第一个版本，并且在根据来自 Reddit 和 QEMU IRC 频道的用户反馈对其进行完善的过程中，学习过程仍然很轻松。我希望我在本文中分享的技巧也能对您有所帮助。