《开源精选》是我们分享Github、Gitee等开源社区中优质项目的栏目，包括技术、学习、实用与各种有趣的内容。本期推荐的Jekyll 是一个简单的、支持博客的、静态站点生成器，非常适合个人、项目或组织站点。

把它想象成一个基于文件的 CMS，没有那么复杂。Jekyll 获取您的内容，呈现 Markdown 和 Liquid 模板，并吐出一个完整的静态网站，准备好由 Apache、Nginx 或其他 Web 服务器提供服务。

快速开始

先决条件Permalink

Jekyll 需要以下内容：

• Ruby version 2.5.0 or higher
• RubyGems
• GCC and Make

安装指示

1 安装所有先决条件。

2 安装 jekyll 和 bundler gems。

gem install jekyll bundler

3 创建一个新的 Jekyll 站点在./myblog.

jekyll new myblog

4 切换到新目录。

cd myblog

5 构建站点并使其在本地服务器上可用。

bundle exec jekyll serve

6 浏览到http://localhost:4000

命令行用法

Jekyll gem 使jekyll您可以在终端中使用可执行文件。

该jekyll程序有几个命令，但结构始终是：

jekyll command [argument] [option] [argument_to_option]

Examples:
    jekyll new site/ --blank
    jekyll serve --config _alternative_config.yml

通常，您将jekyll serve在本地开发以及jekyll build需要生成站点以进行生产时使用。

以下是一些最常见的命令：

• jekyll new PATH- 在指定路径创建一个新的 Jekyll 站点，该站点具有默认的基于 gem 的主题。将根据需要创建目录。
• jekyll new PATH --blank- 在指定路径创建一个新的空白 Jekyll 站点脚手架。
• jekyll build或jekyll b- 一次性构建您的网站./_site（默认情况下）。
• jekyll serve或jekyll s- 每当源文件更改并在本地提供它时构建您的站点。
• jekyll clean- 删除所有生成的文件：目标文件夹、元数据文件、Sass 和 Jekyll 缓存。
• jekyll help- 显示帮助，可选地用于给定的子命令，例如jekyll help build。
• jekyll new-theme- 创建一个新的 Jekyll 主题脚手架。
• jekyll doctor- 输出任何弃用或配置问题。

渲染过程

对于任何 Jekyll 站点，构建会话由以下顺序的离散阶段组成——设置插件、读取源文件、运行生成器、渲染模板，最后将文件写入磁盘。

虽然上述阶段是不言自明的，但值得剖析的一个阶段是渲染阶段。

渲染阶段可进一步分为三个可选阶段。渲染的每个文件都会通过这些阶段中的一个或多个，具体取决于文件的内容字符串、前端内容和扩展名。这些阶段类似于装配线，一个阶段的输出是后续阶段的输入：

• 解释文件中的 Liquid 表达式
  此阶段计算当前文件中的 Liquid 表达式。默认情况下，解释很浅——因为结果输出中的任何 Liquid 表达式都不会被进一步解释。此外，文件前面的任何 Liquid 表达式都保持不变。
• 释放转换器
  此阶段调用映射到当前文件扩展名的转换器并转换输入字符串。这是 Markdown 转换为 HTML 和 Sass / Scss 转换为 CSS 或 CoffeeScript 转换为 JavaScript 等的时候。由于这个阶段是由文件的扩展名决定的，所以文件中的 Markdown 或 Sass.html将保持不变。
• 填充布局
  到这个阶段，源文件被认为是渲染的，它不会被重新访问。但是，根据文件的扩展名，因此根据前面的内容，确定是否从前一阶段获取输出字符串并放入布局中。虽然 Sass 文件或 CoffeeScript 文件的输出永远不会 放入布局中，但常规文本输出可以根据布局是否已通过前端分配而采用任何一种方式。

页面

页面是内容的最基本构建块。它们对于独立内容（不是基于日期的内容或不是一组内容，如工作人员或食谱）很有用。

添加页面的最简单方法是在根目录中添加一个具有合适文件名的 HTML 文件。您还可以使用.md在构建时转换为 HTML 的扩展在 Markdown 中编写页面。对于具有主页、关于页面和联系页面的站点，根目录和关联的 URL 可能如下所示：

.
  about.md    # => http://example.com/about.html
  index.html    # => http://example.com/
  contact.html  # => http://example.com/contact.html

如果您有很多页面，您可以将它们组织到子文件夹中。_site当您的站点构建时，用于对项目源中的页面进行分组的相同子文件夹将存在于该文件夹中。但是，当页面在前端设置了不同的永久链接时，子文件夹 at_site会相应更改。

.
  about.md          # => http://example.com/about.html
  documentation     # folder containing pages
      doc1.md       # => http://example.com/documentation/doc1.html
  design            # folder containing pages
      draft.md      # => http://example.com/design/draft.html

主题

Jekyll 有一个广泛的主题系统，允许您利用社区维护的模板和样式来自定义您的站点的演示文稿。Jekyll 主题以一种可以被您网站内容覆盖的方式指定插件并打包资产、布局、包含和样式表。

了解基于 gem 的主题

当您创建一个新的 Jekyll 站点（通过运行jekyll new 命令）时，Jekyll 会安装一个站点，该站点使用一个名为Minima的基于 gem 的主题。

对于基于 gem 的主题，网站的某些目录（例如assets、_data、_layouts、_includes和_sass目录）存储在主题的 gem 中，从您的直接视图中隐藏。然而，在 Jekyll 的构建过程中，所有必要的目录都将被读取和处理。

对于 Minima，您只能在 Jekyll 站点目录中看到以下文件：

.
  Gemfile
  Gemfile.lock
  _config.yml
  _posts
      2016-12-04-welcome-to-jekyll.markdown
  about.markdown
  index.markdown

Bundler使用Gemfile和Gemfile.lock文件来跟踪构建 Jekyll 站点所需的 gem 和 gem 版本。

基于 Gem 的主题使主题开发人员可以更轻松地向拥有主题 gem 的任何人提供更新。当有更新时，主题开发人员会将更新推送到 RubyGems。

如果您有主题 gem，您可以（如果您愿意）运行bundle update以更新项目中的所有 gem。或者您可以运行bundle update ，替换为主题名称，例如minima，仅更新主题 gem。主题开发人员所做的任何新文件或更新（例如样式表或包含）都将自动拉入您的项目中。

基于 gem 的主题的目标是让您获得强大的、不断更新的主题的所有好处，而不会让所有主题文件妨碍您，并使您的主要关注点过于复杂：创建内容。

覆盖主题默认值

Jekyll 主题设置默认数据、布局、包含和样式表。但是，您可以使用自己的站点内容覆盖任何主题默认值。

要替换主题中的布局或包含，请在您的_layouts或_includes您要修改的特定文件的目录中制作副本，或者从头开始创建文件，并为其指定与您要覆盖的文件相同的名称。

例如，如果您选择的主题具有page布局，您可以通过在目录中创建自己的page布局_layouts（即_layouts/page.html）来覆盖主题的布局。

要在您的计算机上找到某个主题的文件：

• Runbundle info --path后跟主题 gem 的名称，例如bundle info --path minimaJekyll 的默认主题。
• 这将返回基于 gem 的主题文件的位置。例如，Minima 主题的文件可能位于/usr/local/lib/ruby/gems/2.6.0/gems/minima-2.5.1macOS 上。
• 在 Finder 或 Explorer 中打开主题的目录：

# On MacOS
open $(bundle info --path minima)

# On Windows
# First get the gem's installation path:
#
#   bundle info --path minima
#   => C:/Ruby26-x64/lib/ruby/gems/3.1.1/gems/minima-2.5.1
#
# then invoke explorer with above path, substituting `/` with ``
explorer C:Ruby26-x64librubygems3.1.1gemsminima-2.5.1

# On Linux
xdg-open $(bundle info --path minima)

将打开一个 Finder 或 Explorer 窗口，显示主题的文件和目录。Minima 主题 gem 包含以下文件：

.
  LICENSE.txt
  README.md
  _includes
      disqus_comments.html
      footer.html
      google-analytics.html
      head.html
      header.html
      icon-github.html
      icon-github.svg
      icon-twitter.html
      icon-twitter.svg
  _layouts
      default.html
      home.html
      page.html
      post.html
  _sass
      minima
          _base.scss
          _layout.scss
          _syntax-highlighting.scss
      minima.scss
  assets
      main.scss

清楚地了解主题文件后，您现在可以通过在 Jekyll 站点目录中创建一个类似名称的文件来覆盖任何主题文件。

—END—

开源协议：Apache2.0

开源地址：https://github.com/jekyll/jekyll