Introduction:原文链接

1.什么是 Jekyll?

Jekyll 是一个捆绑了动态组件的解析引擎,使用 ruby gem 生成静态页面,动态组件包括 templates, partials, liquid code, markdown 等。Jekyll 作为一个简单的静态博客生成器而知名。

2.Jekyll 做什么?

Jekyll 安装为一个本地的 ruby gem 服务器。安装了之后,你能在终端中通过 jekyll serve 在指定目录下实现一些事情,比如解析 markdown 或者 textile 文件、计算类别、表情、permalink,和从模板、partials 构建你的页面。

一旦解析完成,Jekyll 将在 _site 文件夹中存储结果。这是为了让你从一个静态的网络服务器上获取所有内容。

你可以把 Jekyll 当做一个标准化的动态博客,事实上它将事先解析内容、模板、每个请求的标签,并将整个网站在本地以静态方式缓存。

3.Jekyll 不是博客软件

Jekyll 是一个解析引擎。

Jekyll 并没有任何内容或者模板或者设计元素。刚开始的时候通常有这样的困惑。Jekyll 并没有任何你在你的网页上使用或者看见的任何东西,你得自己制造。

4.我应该关心什么?

Jekyll 非常简约且高效。理解 Jekyll 最重要的部分是他只需要一个静态 Web 服务器就可以创建一个你网站的静态展示。传统的动态博客,比如 WordPress 需要一个数据库和服务器端代码。繁重的动态博客必须部署在一个缓存层才能最后呈现出 Jekyll 所达到的效果:静态服务内容。

因此如果你想把事情简单化,并且相比一个控制面板你更喜欢命令行的话,来试试 Jekyll 吧。

开发者喜欢 Jekyll,因为我们能用写代码的方式写文章:

  • 能在你最爱的编辑器里用 markdown 或者 textile 写文章。
  • 能在本地写和预览你写的内容。
  • 不需要联网。
  • 能用 git 发布。
  • 能在静态 web 服务器上发布你的博客。
  • 能在 Github Pages 上免费发布。
  • 不需要数据库。

5.Jekyll 如何工作

注意!接下来是一份完整但简明的 Jekyll 工作原理纲要,快速介绍了核心概念但没有使用代码例子。这份说明并不想教你做什么,而是意图给你一个完整的关于 Jekyll 的世界里的事的关系图。学习这些核心概念能帮助你避免一般的挫折,最终将帮助你更好的理解 Jekyll-Bootstrap 的代码例子。

初始化安装

Jekyll 安装完成后,你需要按照 Jekyll 的方式格式化你的网站目录。

基础格式
1
2
3
4
5
6
7
8
9
10
\_config.yml
\_includes
\_layouts
\_posts
\_site
index.html
assets
css
style.css
javascripts

_config.yml 存储配置数据

_includes 局部的布局

_layouts 主要模板,不同的页面或页面部分可以有不同的布局

_posts 你的内容,命名格式要求是 @YEAR-MONTH-DATE-title.MARKUP@

_site 这里是 jekyll 生成的站点

assets 这个文件夹不是必须的结构,代表你自己在根目录下创建的一般文件夹。目录和文件格式不对,jekyll 将什么都不做
(read more: http://jekyllrb.com/docs/usage/)

Jekyll 配置

支持的配置选项在此:http://jekyllrb.com/docs/configuration/

Jekyll 中的内容

Jekyll 中的内容可能是文章或者页面。这些内容对象可以插入一个或多个模板,来建造最后各自的静态页面。

Posts 和 Pages

文章和页面支持 markdown、textile 和 html 格式,可以包含 Liquid 模板语法。同时,二者都能包含预设页面的基础元素,比如标题,url 地址,和自定义元数据。

写文章

创建文章:放置于_posts 文件夹下,采用正确的格式

格式化:文章必须命名为 YEAR-MONTH-DATE-title.MARKUP 并被放在 _posts 目录下。如果数据格式不正确,jekyll 将如何将其识别为 post。日期和标题将从文件名中自动解析出来。并且,每个文件必须有 YAML Front-Matter 预设头。YAML Front-Matter 是制定文件的有效语法指定元数据。

排序:顺序是 Jekyll 的重要组成,否则它将难以确定一个自定义排序策略。Jekyll 中只支持顺时和逆时排序。

由于日期是在文件名中硬编码了的,要改变顺序,你只能改变文件名中的日期。

标签:文章能够将标签作为自己的元数据的一部分。标签可以放在文章的 YAML 头里。模板中你能获取特定文章的标签。这些标签也能加入站点集合。

分类:同样在 YAML 头中文章能够使用多个分类词。分类比标签更有意义是因为在文章的 URL 中将表现出其分类。注意,如果你定义多个分类,比如:

1
2
3
4
---
title : hello world
categories: [lessons, beginner]
---

这种定义表示其类别是 lessons 下的 beginner。而不是 lessons 和 beginner 两个分类。

建页面

创建:可以放置在根目录下或者其他任何不以下划线开头的子目录。

格式化:一个 Jekyll 页面必须包含 YAML Front-Matter。注册一个页面意味着:1)Jekyll 将处理这个页面,2)这个页面对象将存在 site.pages 数组里便于引用。

分类和标签:页面不计算分类和标签,定义这些将毫无效果。

子目录:如果页面在子目录下,其路径将反映在 URL 中:

1
2
3
people
bob
eassy.html

这个页面的URL:http://yourdomain.com/people/bob/essay.html

推荐页面

1
2
3
4
- index.html:根 URL 展示的内容
- 404.html:在根目录下创建,Github Pages 将把这个页面用于你的 404 回应
- sitemap.html:生成一个 sitemap 是 SEO 的好习惯
- about.html:简介

Jekyll 的模板

模板用于包含页面或者文章的内容。所有模板能获取全局站点对象变量:site 以及页面对象变量 page。这个站点变量包含所有可获取的内容和站点的元数据。页面变量包含此刻一渲染的该页面或文章的可获取数据。

创建:放在 _layouts 目录下

格式化:必须是 html 编码,包含 YAML Front Matter。所有模板可以使用 Liquid 代码来操作站点数据

在模板中渲染页面或文章内容:在所有模板中有个特殊的变量:content。content 包含页面或文章的所有内容,包含任何之前定义的子模板的内容。在你模板中渲染 content 变量可以把你的主要内容插入。

1
2
3
4
5
6
<body>
<div id=“sidebar”></div>
<div id=“main”>
\{\{ content }}
</div>
</body>

子模板:子模板与模板的区别在于,他们定义在 layout/template 下,带 YAML Front Matter。这个以为着他们在另外一个模板中被渲染。

Includes:在 _includes 文件夹中你可以定义 include 文件。includes 不是模板,他们是被包含在模板中的代码片段。这样,你可以像在其父模板中一样来处理代码。
任何有效的模板代码都能写在 includes 中。

为模板使用 Liquid

模板大概是 Jekyll 中最让人困惑和受挫的部分了。主要是因为 Jekyll 模板必须使用 Liquid 模板语言。

什么是 Liquid?

Liquid 是一种用 Shopify 开发的安全的模板语言。它被设计成任何人都能在主机上在模板文件中安全执行逻辑。
Jekyll 使用 Liquid 来生成文章内容的最终布局结构,以及作为你站点和数据的主要的接口。

为什么我们必须使用 Liquid?

Github 使用 Jekyll 来支持 Github Pages。Github 无法支持所有类型的代码,于是他们限定开发者使用 Liquid。

Liquid 并不对程序员友好

Liquid 并不是真实代码,他也不想执行真实代码。有一点是没有明确的允许你什么也不能做。还有,你只能获取通过模板明确定义的数据结构。

在 Jekyll 中,如果不使用自定义插件或者hack the gem 你无法改变 Liquid,但是这两个方法 Github Pages 都不支持。

对于程序员来说,这很受挫。

但是与其抱怨,不如与之起舞,适应它。

静态资源

静态资源是指除页面之外的在根目录下所有文件和所有不已下划线开头的目录。他们没有有效的 YAML Front Matter,因此不被当做 Jekyll 页面。一般用于图片、css 和 js 文件。

Jekyll 如何解析文件

记住 Jekyll 是一个处理引擎。他有两种主要的解析类型:

  • 内容解析:textile 或 markdown
  • 模板解析:liquid 模板语言

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

  • 文章和页面文件
  • 模板文件:这些文件在 _layouts 中,包含你博客的模板,在 liquid 语法下的 html 文件。如果 include 文件在模板中被引用,也需要解析。
任意文件和文件夹

非有效页面文件将被当做静态内容,Jekyll 将不做处理,原样存在。

用于解析的格式化文件

我们被要求使用 YAML Front Matter。模板、文章、页面都需要,即使 Matter 是空的。这是 Jekyll 知道你想处理这个文件的唯一方式。

YAML Front Matter 需要放在开头:

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

三个短横表示其开始和结束。其间的数据必须是有效的 YAML。

参数:[http://jekyllrb.com/docs/frontmatter/]

定义需要解析的布局

layout 参数定义插入哪个模板文件。如果一个模板文件定义了布局参数,那么他可以作为子模板被使用。

Jekyll 如何生成最后的静态文件

最后,Jekyll 的工作是生成一份你站点的静态文件。下面是他如何做:

  • 收集数据
  • 计算数据
  • 解析文章和模板
  • 生成输出