原文来自:How Jekyll Works

 本文结构:
    Jekyll 简介
      |– Jekyll 是什么?
      |– Jekyll 做什么?
      |– Jekyll 不是博客软件
      |– 我们为什么要使用 Jekyll
    Jekyll 工作原理
      |– 初始化设置
      |– Jekyll 内容
      |– Jekyll 模板
      |– 使用 Liquid 创建模板
      |– 静态资源
      |– Jekyll 如何解析文件
      |– Jekyll 如何生成静态页面
      |– 结语

简介

Jekyll 是什么?

Jekyll 是一个 ruby 解析引擎,经常用于从动态组件中构建静态网站,如模板、liquid code、markdown等。Jekll 被称为是一个简洁的、适用于博客的、静态网站生成引擎。

Jekyll 做什么?

Jekyll 将作为一个 ruby 解析引擎安装在本地。一旦安装完成,你就可以在终端中进入一个文件目录使用 Jekyll serve ,并对该目录提供一定程度上的 Jekyll 预测:如解析 markdown/textile 文件、计算种类、标签、永久链接、并根据模板构建页面。

一旦解析完成,Jekyll 将结果存储在 _site 静态文件夹中。这样你就可以将此文件夹中的所有内容托管在纯静态服务器上。

你可以认为 Jekyll 是一个标准的动态博客,因为它不需要每一次请求都进行内容、模板、标签地解析。Jekyll 事先前仅作一次解析并将整个站点的缓存存放于文件夹中。

Jekyll 不是博客软件

Jekyll 是一个解析引擎。

Jekyll 不附带任何内容,包括模板和设计元素。这样就造成了开始阶段的换乱和无头绪。Jekyll 也不包含你经常在站点中使用和看到的任何元素,所以你必须去实现它。

我们为什么要使用 Jekyll

Jekyll 非常简单而且高效。最重要的是 Jekyll 实现了静态表现形式,仅需要一个静态服务器即可。传统的动态博客(如 Workpress)需要一个数据库和服务器端代码。Jekyll 下定决心做一个复杂动态博客的缓冲层,提供静态内容。

因此,如果你喜欢把事情变得简单,而且习惯管理面板的命令行,不妨一试 Jekyll。

开发者喜欢 Jekyll 是因为我们书写内容就如写代码一样:

  1. 可以使用 markdown 或 textile 书写内容。
  2. 可以在本地预览、书写内容。
  3. 不要网络连接。
  4. 可以通过 git 发布。
  5. 可以将你的博客托管在静态服务器上。
  6. 可以将博客免费托管在GitHub上。
  7. 不需要数据库。

Jekyll 如何工作

注意:以下是 Jekyll 工作原理完整而简洁的概述。仅介绍 Jekyll 的核心概念而不是代码样例。此段信息不是教你怎么做,而是旨在让您全面了解 Jekyll 世界里正在发生什么。学习这些核心概念能帮助您解决常见的问题,更好的理解 Jekyll-Bootstrap 代码样例。

初始化设置

安装 Jekyll 完成后,你需要按照 Jekyll 的规则来组织你的站点目录。Jekyll-Bootstrap 提供了非常简洁的文件结构。

Jekyll 应用基本的文件格式

Jekyll 期望的站点文件如下所示:

_config.yml
_includes
_layouts
  |-default.html
  |-post.html
_posts
  |-20011-10-25-open-source-is-good.markdown
  |-20011-04-26-hello-world.markdown
_site
index.html
assets
  |-javascripts
  |-css
    |-style.css
  • _config.yml 记录配置信息。
  • _includes 自定义视图。
  • _layout 文章内容的主要加载模板,对于不同的文章或者片段可以使用不同的模板进行加载。
  • _posts 此文件夹包含了动态的文章。文件命名格式为:YEAR-MONTH-DATE-title.MARKUP 。
  • _site 一旦 Jekyll 转换完成,将生成的站点存放于此。
  • assets 此文件夹不是标准 Jekyll 的一部分。(更多:http://jekyllrb.com/docs/usage/

Jekyll 配置

以下链接列举了 Jekyll 支持的各种配置选项http://jekyllrb.com/docs/configuration/

Jekyll 内容

Jekyll 的内容可能是一篇文章,也可能是文章列表。这些内容对象都是从一个或者多个模板生成各自的静态页面。

####文章页 和 列表页
无论是文章页还是列表页,都应该使用 markdown、textile 或 html ,因为其可能包含 Liquid 模板语法。这两种页面都可以包含一些元数据,例如:标题、URL链接、甚至一些自定义的元数据。

####使用文章页

1. 创建文章页
创建文章页并将其放置在_posts目录下。

2. 格式要求
文章页必须以 YEAR-MONTH-DATE-title.MARKUP 命名,并放置在_posts目录下。如果数据格式不符合要求,Jekyll 将无法识别该文件。日期和标题将自动从文件名中进行解析。此外,每个文件在其内容前必须包含 YAML 前缀,YAML 前缀是一个符合 YAML 语法的元数据。

3. 排序
排序是 Jekyll 很重要的部分,因为其很难指定自定义排序策略。只可以根据时间的正序或反序进行排序。

因为时间是包含在文件名中的,所以如果需要改变顺序,就必须改变文件名中的时间。

4. 标签
文章可以被打上标签,作为元数据的一部分。标签可以写在 YAML 前缀里。在模板里,可以通过标签来查找这些文章。这些标签这会被添加至站点集合里。

5. 分类
文章可以通过提供的类别进行一种或多种的分类。类别提供了比标签更加重要的信息,可以体现在给定的 URL 路径中。注意:Jekyll 将以特定的工作方式对文章进行分类。如果一个文章被定义为多个类别,则需要使用列别集合。例如:

1
2
3
4
---
title :  Hello World
categories : [lessons, beginner]
---

这里定义了 “lessons/beginner” 类别。注意:如果你在其他地方没有将其分别作为 “lessons” 和 “beginner” 两个类别出现,这里 Jekyll 将会按一个类别去处理。

####使用列表页

1. 创建列表页
列表页的命名不以下划线开头,并且可以将其放在根目录或者子文件夹的任何位置。

2. 格式要求
为了注册一个 Jekyll 页面,此文件必须包含 YAML 前缀。注册一个页面是指1)Jekyll 将会处理这个页面。2)这个页面将结合模板纳入到 site.pages 中。

3. 分类和标签
列表页不支持分类和标签,所以定义这些将是无效的。

4. 子目录
如果列表页面被放置在子文件夹中,则需要在路径信息中有所体现。例如:

  |-bob
    |-essay.html

则此页面的有效路径为 http://yourdomain.com/people/bob/essay.html

####推荐的页面

  1. index.html
    在根目录下定义索引页面。这样在访问根目录的 URL 时,将会显示此页面。
  2. 404.html
    在根目录下创建一个 404.html 页面,Github 在进行 404 响应时将会加载此页面。
  3. sitemap.html
    创建一个站点地图是 SEO 的习惯。
  4. about.html
    关于页面可以很人性化的给出此站点的信息。

Jekyll 模板

模板用于包含一个列表或者文章的内容。所有的模板都可以访问全站点的可用对象。该站点的变量包含了所有可访问的内容和站点相关的元数据。对于包含了访问数据的变量的页面在这一点上都有所体现。

1.新建模板
新建的模板被放置在 _layouts 目录下。

2.格式要求
模板应该使用 html 编码并且包含 YAML 前缀信息。所有的模板可以包含 Liquid 代码来使用站点数据。

3.在模板中加载列表或者文章内容
在模板中有一个特殊的变量,名为:content 。这个变量可以在任何子模板中加载列表或者文章的内容。只需要在你想引入内容的地方写上 content 变量即可。例如:

1
2
3
4
5
6
<body>
  <div id="sidebar"> ... </div>
  <div id="main">
    { { content } }
  </div>
</body>

正确写法大括号之间是不带空格的

4.子模板
子模板和模板是完全相同的,唯一的区别在于在 YAML 前缀中声明哪个是根模板,哪个是子模板。这实际上就意味着一个模板可以呈现在另一个模板中。

5.可加载文件
在 Jekyll 中你可以定义可以加载文件,并将其放置在 _includes 文件下。可加载文件并不是模板,而是一些需要被模板加载的代码片段。这样的话你仅仅需要维护可加载文件里的代码就可以了,而不需要修改其父模板。

任何有用的模板代码都可在可加载文件中被使用。

使用 Liquid 创建模板

模板化可能是 Jekyll 最混乱和令人头疼的部分。因为 Jekyll 模板必须使用 Liquid 语言进行书写。

####什么是Liquid? Liquid 是一种安全的模板化语言,由Shopify开发维护。Liquid是为在模板中执行逻辑的最终用户使用的,不需要考虑任何有关服务器托管的安全问题。

Jekyll 使用 Liquid 将文章内容按照页面布局结构进行生成,其最为生成站点文章页和列表页的主要接口。

####为什么我们必须使用 Liquid GitHub 使用 Jekyll 来生成 Github 页面。且 GitHub 不支持在其站点上运行任意代码,所以限制了开发者必须使用 Liquid。

####Liquid 编程不友好 这一小段文字意在说明:Liquid 不是真正的代码并且其试图不执行真正的代码。此观点说明 Liquid 在没有被明确允许执行的情况下不能做任何事情。更重要的是,你仅仅可以访问模板中的数据结构。

在 Jekyll 下,在没有入侵解析引擎或者运行自定义插件的情况下,是不可能改变 Liquid 传递内容的。而这两者都不被 GitHub 所支持。

作为一名编程者,这将很是令人抓狂。

我个人的立场是不要投入时间去破解 Liquid。从程序员的角度来看,这确实没有必要。如果你有能力运行自定义的插件(即:运行任意的 ruby 代码),你最好继续使用 ruby。我们已经建立了Mustache-with-Jekyll,但现在已经被遗弃了,请使用http://ruhoh.com进行替代。

静态资源

静态资源是一些在根目录的文件,或者不是以下划线开头的文件夹。因为他们没有有效的 YAML 格式,所以不会被当成 Jekyll 页面去解析。静态资源通常包含一些图片、 CSS 或者 JavaScript 等。

Jekyll 如何解析文件

Jekyll 是一个解析引擎,其中有两种主要类型的解析:

  1. 内容解析
    这个需要使用 markdown 或者 textile
  2. 模板解析
    这个需要使用 Liquid 模板语言

因此有两种主要的文件需要解析:

  1. 文章/列表文件
    在 Jekyll 中不管是文章还是列表,只要是有效的都将使用 markdown 或者 textile 进行解析。
  2. 模板文件
    _layouts 文件夹下的这些文件,包括博客的模板。都应该使用带有 Liquid 语法的 HTML 文件进行编写。所以可加载文件可以很简单得被包含在模板文件中。

####任意文件和文件夹

无效文件将被视为静态内容,跳过 Jekyll 解析直接注入在博客结构中。

####解析格式化文件

我们列出了有效的 YAML 前缀格式。模板、文章页、列表页等都需要提供有效的 YAML 前缀信息,即使前缀信息为空。因为只有这种方式才可以让 Jekyll 明白你需要处理的文件。

YAML 前缀信息必须写在页面的开头:

1
2
3
4
5
6
---
layout: post
category : pages
tags : [how-to, jekyll]
---
... contents ...

在 YAML 前缀开始处,有三个短横线组成的新行;在其结尾处,也有三个短横线组成的新行。YAML 信息只有包含在此块中才有效。更详细的 YAML 前缀配置信息见A comprehensive explanation of YAML Front Matter

####定义文章结构和解析模板

YAML 前缀中的 layout 参数定义了使用哪个模板加载此文件。如果一个模板文件被作为 layout 参数使用,那么这个模板被称为子模板。就是说加载文章到一个模板中和一个模板文件作为嵌套子模板进行加入是类似的。

Jekyll 如何生成静态页面

最终,Jekyll 的工作是生成站点的静态形式。以下是如何做到这点的概述:

  1. Jekyll 搜集数据 Jekyll 扫描 _posts文件夹,搜集所有的posts文件并将其作为post对象。然后扫描结构资源并进行搜集。最终扫描其他的目录来寻找pages。
  2. Jekyll 计算数据 Jekyll 使用这些对象,来计算元信息(如:永久链接、标签、类别、标题、时间等)。然后构造一个非常大的站点对象,包含了所有的posts、pages、layouts和相关的元信息。至此,你的站点将是一个非常大的 ruby 对象。
  3. Jekyll 分析文章和模板 下一步,Jekyll 循环遍历每一个 post 文件并通过 markdown 或 textile 进行转换。然后将 post 放置相应的 layout 中。一旦 post 解析完成并将内容放置在正确的 layout 结构中,我们称 layout 为 “liquified”。

    Liquification 被定为如下: Jekyll 初始化 Liquid 模板,通过简单的哈希对象来表示 ruby 站点或者 post 对象。这些简化的数据结构可以在模板中进行访问。
  4. Jekyll 产生输出 最终,Liquid 模板进行渲染。执行 Liquid 语法,根据模板产生并保存最终的静态文件。

注意:
如果你是 Jekyll 的最终用户,你的 API 仅有两部分组成:

  1. 你创建目录的方式。
  2. Liquid 语法和在 Liquid 模板中使用的变量。

在模板中可以使用的所有数据对象在 Jekyll Bootstrap API 章节中都有所列举。你也可以查阅原始文档http://jekyllrb.com/docs/variables/

结语

我希望这些清晰地描述了 Jekyll 正在做什么以及为什么会以这样的方式工作。如上所述,我们主要的编程约束就是 API 仅仅支持 Liquid 访问。

Jekyll-Bootstrap 正在试图提供更加直观、简洁的 Jekyll 工作方式和策略。

感谢您本次阅读!