Jekyll 中的配置和模板语法

Jekyll 中的配置和模板语法

配置

文件介绍

_config.yml

Jekyll 的全局配置文件。
比如网站的名字，网站的域名，网站的链接格式等等。

_drafts

未发布的 posts 存放的地方，这里的 post 文件名不需要加日期标记。

_includes

该目录下的文件内容是最终要放进模版文件中的一些代码片段。
对于网站的头部，底部，侧栏等公共部分，为了维护方便，我们可能想提取出来单独编写，然后使用的时候包含进去即可。
这时我们可以把那些公共部分放在这个目录下，使用时只需要引入即可。

{ % include filename % }

_layouts

存放一些模版文件，模版是用来包含并装饰 page 或 post 内容的。Jekyll 的模版使用 HTML 语法来写，并包含 YAML Front Matter。
所有的模版都可用 Liquid 来与网站进行交互，都可以使用全局变量 site 和 page 。

site 变量: 包含该网站所有可以接触得到的内容和元数据(meta-data)
page 变量: 包含的是当前渲染的page或post的所有可以接触得到的数据

对于网站的布局，一般会写成模板的形式，这样对于写实质性的内容时，比如文章，只需要专心写文章的内容，然后加个标签指定用哪个模板即可。
对于内容，指定模板了模板后,我们可以称内容是模板的儿子。
为什么这样说呢？ 因为这个模板时可以多层嵌套的，内容实际上模板，只不过是叶子节点而已。

在模板中，引入儿子的内容：

{ { content } }

在儿子中，指定父节点模板：

注意，必须在子节点的顶部。

---
layout: post
---

_posts

发布的内容，比如博客文章，常放在这里面，而且一般作为叶子节点。
文件的命名必须遵循：YEAR-MONTH-DAY-title.markdown。

另外，所有放在根目录下并且不以下划线开头的文件夹中有格式的文件都会被 Jekyll 处理成 page。
这里说的有格式是指含有 YAML Front Matter 头部的文件。

所有的 post 和 page 都要用 markdown 或者 texile 或者 HTML 语法来写，可以包含 Liquid 模版的语法。而且必须要有 YAML Front Matter 头部( Jekyll 只处理具有 YAML Front Matter 的文件)。

YAML Front Matter 必须放在文件的开头，一对---之间，用户可在这一对---间设置预先定义的变量或用户自己的数据。具体看下面的 说明。

_data

Jekyll 支持从该目录中加载 YAML、 JSON、 和 CSV 格式（.yml、yaml、json或csv扩展名）的文件数据。用于配置一些全局变量，不过数据比较多，所以放在这里。
比如，多人参与网站开发，我们通常会在这里面定义一个members.yml文件。

例如文件内容为：

- name: Tom Preston-Werner
  github: mojombo

- name: Parker Moore
  github: parkr

然后在模板中我们就可以通过site.data.members(注意：文件名决定变量名)使用这些数据。

<ul>
{ % for member in site.data.members % }
  <li>
    <a href="https://github.com/{ { member.github } }">
      { { member.name } }
    </a>
  </li>
{ % endfor % }
</ul>

_site

Jekyll 生成的网页默认输出的地方，一般需要在.gitignore中屏蔽掉这个目录。

index.html

主页文件，后缀有时也用 index.md 等。
这个需要根据自己的需要来写，因为不同的格式之间在某些情况下还是有一些细微的差别的。

其他静态资源

对于其他静态资源，可以直接放在根目录或任何其他目录，然后路径和平常的网站一样，按路径来找链接中的文件。

配置全局变量

虽然全局变量都有自己的 默认配置，但是我们往往会手动配置为自己心中最好的效果。
另外，一些全局变量既可以在配置文件中设置，也可以在命令行选项参数里指定。

注意，配置不用使用 tab，否则可能会忽略那条命令。

源代码的位置

这个一般不配置，默认即可。

source: DIR

当然编译的时候也可以指定，但是使用 github 我们是不能指定参数的。

-s, --source DIR

输出网站位置

这个一般也是默认。

# 编译参数 -d, --destination DIR
destination: DIR #配置语法

Safe 开关

官方文档上就一句话：

Disable custom plugins, and ignore symbolic links.

大概意思是禁用常用的插件，忽略符号链接。

# 编译参数  --safe
safe: BOOL

Base URL

将 Jekyll 生成的网站内容放置在域名的子路径下面。

我们经常需要在多个地方运行 Jekyll，如发布到 GitHub Pages 前在本地预览下网站。--baseurl标记就是为此而生的。

首先在_config.yml文件添加baseurl，然后在网站各个链接的地方加前缀``。
当jekyll serve预览本地网站时，在本地域名后追加--baseurl的值（类似/这样的路径）。

# baseurl: "/blog"  编译参数: --baseurl URL
baseurl: URL

注意：所有的 page 和 post 的 URL 都是以斜线/领头，那么当site.baseurl=/时，连接的 URL 会出现两个重复的/而破坏超链接。因此，建议只在baseurl有具体值时才使用site.baseurl给 URL 加前缀。

忽略文件

这个很有用，有时候你写了一个文件，里面的一个东西可能会被 Jekyll 处理，但是你不想让 Jekyll 处理的话，就使用这个语法忽略那些文件。

exclude: [DIR, FILE, ...]

强制处理文件

有时候我们的一些文件的名字由于不在 Jekyll 处理的文件名字范围内，这时候就需要强制处理这些文件了。比如.htaccess文件。

# include: [".htaccess"]
include: [DIR, FILE, ...]

时区

模板中经常会对时间进行转换，这个时候如果至指定时区的话，可能得到的时间会和我们想要的时间错几个小时。在 这里 能查看到可用的值。

# timezone: Asia/Shanghai
timezone: TIMEZONE

编码

大家都是程序员，就不用多说了。
执行ruby-e'puts Encoding::list.join("\n")'可列出本地 Ruby 可用的编码。

# encoding : utf-8
encoding: ENCODING

文章链接格式

我们可以自定义 Post 的 URL 格式，通过 permalink 来配置。比如：

# 设定 permalink 取值
permalink: /:year/:month/:day/:title.html
# 那么 post: 2014-10-19-slap-chop.md 最终输出的路径 URL 变成
# /2014/10/19/slap-chop.html

permalink: /:month-:day-:year/:title  # => /04-29-2009/slap-chop/index.html

permalink: pretty    # => /2009/04/29/slap-chop/index.html

另外，还有3种内置的链接格式可以使用：

分页

通常我们都不想把所有的 Post 都放在一页显示，而是要分成多页显示。好在 Jekyll 支持分页显示，通过paginate和paginate_path两个变量来设置每页显示的数量和分页 HTML 的 URL 路径。

paginate: 5
paginate_path: "blog/page:num/"

根据上面的配置，Jekyll 会读取blog/index.html文件，把每页赋值给全局变量paginator，并输出 HTML 分页文件，如：第2页为blog/page2/index.html。其中，“page” 是字符常量，变量:num是分页的页码，自动从 2 开始编码，因此在罗列所有页面页码及它们的超链接时要注意一下，首页链接没有中间的 “page1” 路径。
通过paginator的相关属性我们可以实现在不同页间切换。