Jekyll

本博客内容取自jekyll官网

Jekyll 是一个简单的博客形态的静态站点生产机器。它有一个模版目录，其中包含原始文本格式的文档，通过一个转换器（如 Markdown）和 Liquid 渲染器转化成一个完整的可发布的静态网站。

环境配置

1.下载安装Ruby

2.下载RubyGems，解压之后，在其目录下执行 ruby setup.rb

3.检查是否安装成功：ruby -v 和 gem -v

4.安装jekyll：gem install jekyll ，检查版本：jekyll -v

5.安装bundler：gem install bundler

常用命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 创建
jekyll new myblog

# 当前文件夹中的内容将会生成到 ./_site 文件夹中
jekyll build
# 当前文件夹中的内容将会生成到 ./_site 文件夹中，会查看改变，并且自动再生成
# 在构建过程中对 _config.yml 的修改将不会被监测
jekyll build --watch

# 运行，且默认会监测代码变化，自动重新运行修改后的代码
# 在运行过程中对 _config.yml 的修改将不会被监测
cd myblog
jekyll serve
# --no-watch 不会监测变化
jekyll serve --no-watch
# 脱离终端在后台运行，关闭方式：ps aux | grep jekyll查看进程号，然后kill -9 ID
jekyll serve --detach

# 使用bundle运行
bundle exec jekyll serve
# 打开浏览器，访问http://localhost:4000，即可查看博客

目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
.
├── _config.yml
├── _drafts
|   ├── begin-with-the-crazy-ideas.textile
|   └── on-simplicity-in-technology.markdown
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2007-10-29-why-every-programmer-should-play-nethack.textile
|   └── 2009-04-26-barcamp-boston-4-roundup.textile
├── _site
├── .jekyll-metadata
└── index.html

配置文件 _config.yml

既可以配置在网站根目录下的_config.yml 文件，也可以作为命令行的标记来配置。

_config.yml 包括一些在运行时一次性读入的全局配置和变量定义，在自动生成的过程中并不会重新加载，除非重新运行。

全局配置

选项表示配置到配置文件中；标记表示配置到命令行中

Destination 文件夹会在站点建立时被清理

<destination> 的内容默认在站点建立时会被自动清理。不是创建的文件和文件夹会被删除。

想在 <destination> 保留的文件和文件夹应在 <keep_files> 里指定。

不要把<destination> 设置到重要的路径上，而应该把它作为一个暂存区域,从那里复制文件到web服务器。

编译选项

服务选项

除了下边的选项， serve 命令还可以接收 build 的选项，当运行网站服务之前的编译时候使用。

不要在配置文件中使用 tab 制表符，这将造成解析错误，或倒回到默认设置，请使用空格替代。

自定义 WEBRick 标题

在 _config.yml 中为站点提供自定义标题

1
2
3
4
5
# 文件: _config.yml
webrick:
  headers:
    My-Header: My-Value
    My-Other-Header: My-Other-Value

指定build时的环境

在 build（或serve）参数中，能指定 Jekyll 的环境和参数。然后 build 会将参数应用在内容中任意的条件语言。

例如，在代码中的条件语句中应用设置：

1
2
3
{% if jekyll.environment == "production" %}
   {% include disqus.html %}
{% endif %}

当 build Jekyll 网站时，if 语句块中的内容不会被执行；除非在 build 命令中还指定了一个 production 环境，像这样：

1
JEKYLL_ENV=production jekyll build

JEKYLL_ENV 的默认值是 development。

环境参数可以任意设置（不止是 development 或者 production ）。

在 build 命令中指定参数，当迁移环境时，可以避免更改配置文件中的值。

头信息默认值 defaults

• 通过使用YAML 头信息可以指定站点的页面和文章的配置。

• Jekyll 提供方法在站点配置中设置默认值，而不是在每次创建一个新的文章或页面重复此配置。

• 要做到这一点，可以在项目根目录下的 _config.yml 文件里设置 defaults 的值指定全站范围的默认值。

• defaults 保存一个范围/值的对的数组，指定了默认值要设置给某个特定文件路径下的全部文件，或者在该路径下某特定文件类型的文件。

（1）全部文件：

1
2
3
4
5
6
defaults:
  -
    scope:
      path: "" # 一个空的字符串代表项目中所有的文件
    values:
      layout: "default"

（2）指定类型

1
2
3
4
5
6
7
defaults:
  -
    scope:
      path: "" # 一个空的字符串代表项目中所有的文件
      type: "posts"
    values:
      layout: "default"

只会给类型是 posts 的文件设置默认布局。

type取值： pages ， posts ， drafts 或者站点中的集合。

当创建一个范围/值的对，如果选择了 type，就必须指定一个值给 path 。

（3）多个范围/值的对

1
2
3
4
5
6
7
8
9
10
11
12
13
14
defaults:
  -
    scope:
      path: ""
      type: "posts"
    values:
      layout: "my-site"
  -
    scope:
      path: "projects"
      type: "pages"
    values:
      layout: "project" # 覆盖之前的默认布局
      author: "Mr. Hyde"

所有的文章posts都会使用 my-site 布局。

projects/ 文件夹下的 html 文件会使用 project 布局，也会拥有值为 Mr. Hyde 的 page.author 变量。

使用更具体的路径projects/，可以把在 projects/ 路径下的文件的默认布局设置为 project ，而非my-site。

（4）设置集合的默认值

1
2
3
4
5
6
7
8
9
10
11
collections:
  - my_collection:
    output: true

defaults:
  -
    scope:
      path: ""
      type: "my_collection" # 站点里的一个集合，复数形式
    values:
      layout: "default"

在 collection 里面 layout 被设为 default

用 my_collection 的名字来设置type

（5）优先权

可以在页面或文章的文件里覆盖 _config.yml 的 defaults 部分的设定。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# In _config.yml
...
defaults:
  -
    scope:
      path: "projects"
      type: "pages"
    values:
      layout: "project"
      author: "Mr. Hyde"
      category: "project"
...
# In projects/foo_project.md
---
author: "John Smith"
layout: "foobar"
---
The post text goes here...

projects/foo_project.md 的布局会是 foobar而不是project ， author 是 John Smith而不是 Mr. Hyde

默认配置

Jekyll 默认使用以下的配置运行

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
# 目录结构
source:      .
destination: ./_site
plugins:     ./_plugins
layouts:     ./_layouts
data_source: ./_data
collections: null

# 阅读处理
safe:         false
include:      [".htaccess"]
exclude:      []
keep_files:   [".git", ".svn"]
encoding:     "utf-8"
markdown_ext: "markdown,mkdown,mkdn,mkd,md"

# 内容过滤
show_drafts: null
limit_posts: 0
future:      true
unpublished: false

# 插件
whitelist: []
gems:      []

# 转换
markdown:    kramdown
highlighter: rouge
lsi:         false
excerpt_separator: "\n\n"
incremental: false

# 服务器选项
detach:  false
port:    4000
host:    127.0.0.1
baseurl: "" # does not include hostname

# 输出
permalink:     date
paginate_path: /page:num
timezone:      null

quiet:    false
defaults: []

# Markdown 处理器
rdiscount:
  extensions: []

redcarpet:
  extensions: []

kramdown:
  auto_ids:       true
  footnote_nr:    1
  entity_output:  as_char
  toc_levels:     1..6
  smart_quotes:   lsquo,rsquo,ldquo,rdquo
  enable_coderay: false

  coderay:
    coderay_wrap:              div
    coderay_line_numbers:      inline
    coderay_line_number_start: 1
    coderay_tab_width:         4
    coderay_bold_every:        10
    coderay_css:               style

配置设置的优先顺序如下：

1. 命令行标志
2. 配置文件设置
3. 默认配置

Liquid 选项

Liquid的错误处理方式可以通过 error_mode 来配置，可选项有：

• lax — 忽略所有错误
• warn — 针对每个错误在控制台中输出警告信息
• strict — 输出错误信息并停止构建过程

Markdown 选项

Jekyll 支持的 Markdown 渲染器中有的有额外的选项。

Redcarpet

Kramdown

设置Github Flavored Markdown：

1
2
kramdown:
  input: GFM

自定义 Markdown 处理器

在 Jekyll::Converters::Markdown 的命名空间下新建一个类：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
class Jekyll::Converters::Markdown::MyCustomProcessor
  def initialize(config)
    require 'funky_markdown'
    @config = config
  rescue LoadError
    STDERR.puts 'You are missing a library required for Markdown. Please run:'
    STDERR.puts '  $ [sudo] gem install funky_markdown'
    raise FatalException.new("Missing dependency: funky_markdown")
  end

  def convert(content)
    ::FunkyMarkdown.new(content).convert
  end
end

一旦建立了类，并且它作为一个插件被正确安装到 _plugins 文件夹 或者 作为 gem 被正确安装，要在 _config.yml 里指定它：

1
markdown: MyCustomProcessor

YAML 头信息

任何只要包含 YAML 头信息的文件在 Jekyll 中都能被当做一个特殊的文件来处理。

头信息必须在文件的开始部分，并且需要按照 YAML 的格式写在两行三虚线之间。

1
2
3
4
---
layout: post
title: Blogging Like a Hacker
---

可以在两行三虚线之间定义变量。

头信息变量是可选的，如果想使用Liquid标签和变量，但在头信息中不需要任何定义，那就让头信息空着。

预定义的全局变量

自定义变量

假如自定义了title变量title: Blogging Like a Hacker，可以{{ page.title }}使用title的值。

文章的预定义变量

撰写博客 _posts/

文件名要求

4位年-2位月-2位日-标题.后缀名

文件格式

所有博客文章顶部必须有一段 YAML 头信息，之后可以正常撰写内容。

引用图片及其他资源

在工程的根目录下创建一个文件夹，命名为assets ，将图片文件、下载文件或者其它的资源放到这个文件夹下。

在任何一篇文章中，都可以用站点的根目录来进行引用，即{{ site.url }}。

引用图片

1
![有帮助的截图]({{ site.url }}/assets/screenshot.jpg)

链接可下载的PDF文件

1
[下载 PDF]({{ site.url }}/assets/mydoc.pdf).

如果网页只在域名的根 URL 下做展示，可以不使用 {{ site.url }} 变量，直接使用 /path/file.jpg 即可。

文章列表

1
2
3
4
5
6
7
<ul>
  {% for post in site.posts %}
    <li>
      <a href="{{ post.url }}">{{ post.title }}</a>
    </li>
  {% endfor %}
</ul>

文章摘要

Jekyll 会自动取每篇文章从开头到第一次出现 excerpt_separator 的地方作为文章的摘要，并将此内容保存到变量 post.excerpt 中。

• 可以在文章的 YAML 头信息中增加 excerpt 来覆盖自动摘要。

• 可以在文章中自定义一个 excerpt_separator。
• 可以在 _config.yml 中全局声明 excerpt_separator，可以设置为空“”。
• 可以通过| strip_html过滤器来移除输出内容中的html标签。

自定义excerpt_separator

1
2
3
4
5
6
7
---
excerpt_separator: <!--more-->
---

Excerpt
<!--more-->
Out-of-excerpt

高亮代码片段

Jekyll 自带语法高亮功能，可以选择使用 Pygments 或 Rouge 两种工具中的一种。

在文章中插入一段高亮代码非常容易，只需使用下面的 Liquid 标记：

1
2
3
{% highlight ruby %}
....
{% endhighlight %}

ruby是需要高亮的代码语言类型

显示行数

1
2
3
{% highlight ruby linenos %}
....
{% endhighlight %}

草稿 _drafts/

草稿是没有日期的文章。它们是还在创作中而暂时不想发表的文章。

想要开始使用草稿，需要在网站根目录下创建一个名为 _drafts 的文件夹，并新建第一份草稿：

1
2
|-- _drafts/
|   |-- a-draft-post.md

为了预览拥有草稿的网站，运行带有 --drafts 配置选项的 jekyll serve 或者 jekyll build。

此两种方法皆会将该草稿的修改时间赋值给草稿文章作为其发布日期，所以将看到当前编辑的草稿文章作为最新文章被生成。

页面布局 _layouts/

• layouts（布局）是包裹在文章外部的模板。
• 布局可以在YAML 头信息中根据不同文章进行选择。
• 标签 {{ content }} 可以将content插入页面中。
• 不管是html还是md文件，都可以通过设置YAML头信息来设置layout
• layout也可以在_config.yml中设置defaults的属性来进行全局的设置

例如：

在_layouts/post.html中

1
2
3
....
{{ content }}
....

在_posts/blog.md中设置YAML头信息

1
2
3
---
layout:     post
---

这样，博客的内容就会自动被包裹在post.html的content部分。

创建页面

主页 index.html

index.html是主页。

站点上任何 HTML 文件（包括主页）都可以使用 layout 和 include 中的内容作为公用的内容。

创建页面的两种方法

• 将为页面准备的命名好的 HTML 文件或者 Markdown 文件放在站点的根目录下。
• 在站点的根目录下为每一个页面创建一个文件夹，并把 index.html 文件或者 index.md 放在每个文件夹里。

这两种方法都可以工作（并且可以混合使用），它们唯一的区别就是访问的 URL 样式不同。

（1）直接放在根目录

这样的 URL 将包含文件的后缀名

1
2
3
4
5
6
7
8
9
10
.
|-- _config.yml
|-- _includes/
|-- _layouts/
|-- _posts/
|-- _site/
|-- about.html    # => http://example.com/about.html
|-- index.html    # => http://example.com/
|-- other.md      # => http://example.com/other.html
└── contact.html  # => http://example.com/contact.html

（2）创建各自的文件夹

为每个顶级页面创建一个文件夹，并包含一个 index.html 文件。

这样的 URL 将以文件夹的名字作为结尾，而不包含文件的后缀名

1
2
3
4
5
6
7
8
9
10
11
12
13
.
├── _config.yml
├── _includes/
├── _layouts/
├── _posts/
├── _site/
├── about/
|   └── index.html  # => http://example.com/about/
├── contact/
|   └── index.html  # => http://example.com/contact/
|── other/
|   └── index.md    # => http://example.com/other/
└── index.html      # => http://example.com/

也可以使用头变量permalink实现不显示文件的后缀名

例如：在 other.md 文件的头信息中定义：permalink: /other，就得到 URL http://example.com/other

静态文件

静态文件不包含任何 YAML 头信息，譬如图片、PDF 和其他不必渲染的内容。

它们在 Liquid 中可以通过 site.static_files 访问，还包括以下元数据：

常用变量

Jekyll 会遍历网站搜寻要处理的文件。任何有 YAML 头信息的文件都是要处理的对象。

对于每一个这样的文件，Jekyll 都会通过 Liquid 模板工具来生成一系列的数据。

全局(Global)变量

全站(site)变量

1
2
3
4
5
6
7
8
{% for tag in site.tags %}

{{ tag[0] }} // 是 tag name
{{ tag[1] }} // 包含 tag 下的 posts

{% endfor %}

//categories同理

页面(page)变量

任何自定义的头文件信息都会在 page 中可用。

举例来说，如果在Page 的头文件中设置了 custom_css: true，这个变量就可以被取到 page.custom_css。

如果头文件信息定义在一个layout中，可以通过全局变量layout获取变量。

举例来说，如果设置 class: full_page ，在layout中可以通过 layout.class来获取它。

分页器(Paginator)

这些变量仅在首页index.html文件中可用，不过也会存在于子目录中，就像 /blog/index.html。

集合

集合（Collection）允许定义一种新的文档类型，它既可以像页面和文章那样工作，也可以拥有它们特有的属性和命名空间。

使用集合

（1）设置集合

将下面的代码加入 _config.yml 文件，将 my_collection 替换为集合的名字。

1
2
collections:
  my_collection

可以在 _config.yml为集合加入具体的元数据：

1
2
3
collections:
  my_collection:
    foo: bar

集合也可以设置默认的属性：

1
2
3
4
5
6
defaults:
  - scope:
      path: ""
      type: my_collection
    values:
      layout: page

这个代码将所有的my_collection的 layout 被设为 page 。

（2）加入集合的文档

• 创建对应的文件夹（如 <source>/_my_collection）并添加文件。

• 若 YAML 头信息存在，文件将被作为数据读入，并且其后的任何信息都将被保存在文档的content 属性中。

• 如果没有任何 YAML 头信息存在， Jekyll 将不会在集合中生成任何文件。

• 文件夹名称必须和在_config.yml中定义的集合名称完全一致，包括前缀的_字符。

（3）渲染集合文件为独立文件

如果希望 Jekyll 对每一个集合中的文件，都创建一个公开的渲染后的版本，在_config.yml中，将集合的元数据中将output键设置为true：

1
2
3
collections:
  my_collection:
    output: true

这将会依据每一个在集合中的文档创建一个文件。

例如，有一个_my_collection/some_subdir/some_doc.md文件，它将利用 Liquid 以及选用的 Markdown 转换器创建一个<dest>/my_collection/some_subdir/some_doc.html文件。

（4）集合的permalink

文件的URL也可以通过对集合的permalink元数据进行设置来自定义。

1
2
3
4
collections:
  my_collection:
    output: true
    permalink: /awesome/:path/

例如，有一个_my_collection/some_subdir/some_doc.md文件，它将写入到<dest>/awesome/some_subdir/some_doc/index.html路径下。

Liquid 属性

集合

使用site变量可以访问集合。

例如，若希望获取_albums/中的集合albums，可以使用site.albums变量。

每个集合都具有一个它本身的文档数组（例如，site.albums就是一个文档组成的数组，和site.pages、site.posts类似）。

集合可以通过site.collections获取，其中包含在_config.yml中定义的元数据和下面的信息：

文档

作为文档 YAML 头信息的补充，每一个文档还具有以下属性。

获取集合的属性

在站点的任何位置，都可以获取在 YAML 头中的属性。

通过上面的示例，配置一个site.albums集合，并在对应的文件的头信息中创建如下结构的数据（需要使用引擎支持的标记语言，且不能以.yaml作为扩展名）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
title: "Josquin: Missa De beata virgine and Missa Ave maris stella"
artist: "The Tallis Scholars"
director: "Peter Phillips"
works:
  - title: "Missa De beata virgine"
    composer: "Josquin des Prez"
    tracks:
      - title: "Kyrie"
        duration: "4:25"
      - title: "Gloria"
        duration: "9:53"
      - title: "Credo"
        duration: "9:09"
      - title: "Sanctus & Benedictus"
        duration: "7:47"
      - title: "Agnus Dei I, II & III"
        duration: "6:49"

若要在一个页面中列出集合中的专辑（album），可以使用下面的模板：

1
2
3
4
5
6
7
8
9
10
11
12
13
{% for album in site.albums %}
  <h2>{{ album.title }}</h2>
  <p>Performed by {{ album.artist }}</p>
  {% for work in album.works %}
    <h3>{{ work.title }}</h3>
    <p>Composed by {{ work.composer }}</p>
    <ul>
    {% for track in work.tracks %}
      <li>{{ track.title }} ({{ track.duration }})</li>
    {% endfor %}
    </ul>
  {% endfor %}
{% endfor %}

数据文件 _data/

• _data 目录用于存储供 Jekyll 生成网站的附加数据。

• 文件可以为 .yml、.yaml、.json、csv ，并可通过 site.data 访问，注意csv文件必须包含表头行。

• 这个强大的特性可以帮避免模板中的重复，并能在不修改 _config.yml 的情况下设置网站特定的选项。

• 插件和主题也可以通过数据文件来配置变量。

• 数据文件包括在自动生成范围内，可以在更改后自动重新加载。

（1）成员列表

_data/members.yml:

1
2
3
4
5
6
7
8
- name: Tom Preston-Werner
  github: mojombo

- name: Parker Moore
  github: parkr

- name: Liu Fengyun
  github: liufengyun

或 _data/members.csv:

name,github
Tom Preston-Werner,mojombo
Parker Moore,parkr
Liu Fengyun,liufengyun

这些数据可以通过 site.data.members 访问（注意文件名决定变量名members）。

可以在模板中使用该成员列表：

1
2
3
4
5
6
7
8
9
<ul>
{% for member in site.data.members %}
  <li>
    <a href="https://github.com/{{ member.github }}">
      {{ member.name }}
    </a>
  </li>
{% endfor %}
</ul>

（2）组织结构

数据文件也可以被放在 _data 的子目录下，每层目录都将添加进变量的命名空间。

下面的示例展示了如何在 orgs 目录下分别定义 GitHub 的组织结构：

_data/orgs/jekyll.yml:

1
2
3
4
5
6
7
8
username: jekyll
name: Jekyll
members:
  - name: Tom Preston-Werner
    github: mojombo

  - name: Parker Moore
    github: parkr

_data/orgs/doeorg.yml:

1
2
3
4
5
username: doeorg
name: Doe Org
members:
  - name: John Doe
    github: jdoe

通过 site.data.orgs 加上各自的文件名访问：

1
2
3
4
5
6
7
8
9
10
11
<ul>
{% for org_hash in site.data.orgs %}
{% assign org = org_hash[1] %}
  <li>
    <a href="https://github.com/{{ org.username }}">
      {{ org.name }}
    </a>
    ({{ org.members | size }} members)
  </li>
{% endfor %}
</ul>

（3）访问特定的作者

页面和文章也可以访问特定的数据项目，下面的例子展示了如何实现：

_data/people.yml:

1
2
3
dave:
    name: David Smith
    twitter: DavidSilvaSmith

然后可在文章的头信息中指定作者：

1
2
3
4
5
6
7
8
9
10
11
---
title: sample post
author: dave
---

{% assign author = site.data.people[page.author] %}
<a rel="author"
  href="{{ author.twitter }}"
  title="{{ author.name }}">
    {{ author.name }}
</a>

资源 _sass/

Jekyll 提供了对 Sass 的内建支持，还能通过安装相应的 Ruby gem 支持 CoffeeScript。

使用时只需创建以 .sass、.scss 或 .coffee 为扩展名的文件，并以两行 — 开头即可，例如：

1
2
3
4
5
6
---
---

// start content
.my-definition
  font-size: 1.2em

Jekyll 将这些文件的输出存放在同一目录下，例如网站源目录下的 css/styles.scss，Jekyll 会处理生成网站目标目录下的 css/styles.css。

为了确保 Coffeescript 能在 Jekyll 3.0 使用，必须：

• 安装 jekyll-coffeescript gem
• 确保 _config.yml 包含下列设置并更新（即重新 jekyll serve）：

1
2
gems:
 - jekyll-coffeescript

模板

Jekyll 使用 Liquid 模板语言，支持所有标准的 Liquid 标签和过滤器。

Jekyll 甚至增加了几个过滤器和标签，方便使用。

过滤器 |

Slugify 的可选参数

Slugify 接受一个参数，用来设定具体的过滤字符。默认值为default。可选参数如下（含过滤字符）：

• none：不过滤字符
• raw：空格
• default：空格和非字母数字字符
• pretty：空格和非字母数字字符，._~!$&'()+,;=@除外

引用 _includes/

所有被引用的文件放在根目录的 _includes 文件夹

如果需要在多个地方引用一小代码片段，可以使用 include 标签。

1
{% include footer.html %}

上述代码将把 <source>/_includes/footer.html 的内容包含进来。

也可以使用 Liquid 标记的变量：

1
{% include {{my_variable}} %}

还可以对 include 传递参数。省略引用标记来传递变量， Liquid 弯括号不能在此处使用：

1
{% include footer.html param="value" variable-param=page.variable %}

这些传递的变量可以通过 Liquid 调用：

1
{{ include.param }}

引入的内容未必总在 _includes 文件夹，也可以选择相对当前文件，引入其他文件的片段：

1
{% include_relative somedir/footer.html %}

当该标签被使用时，引入的内容应位于对应的相对路径下。

例如，_posts/2014-09-03-my-file.markdown文件使用了include_relative标签，引入的文件需要位于 _posts 文件夹或其子文件夹。在其他路径下将无法引入。

include 标签的其他特征也同样适用于 include_relative 标签，如使用变量。

标签

代码高亮

Jekyll 已经支持超过 60 种语言的代码高亮显示。

Rouge 在 Jekyll 3 及以上版本是默认高亮脚本。

也可以使用 Pygments 实现代码高亮。要使用 Pygments，必须在系统上安装 Python，安装 pygment.rb gem 并在配置文件中设置 highlighter 为 pygments。

使用代码高亮的例子如下：

1
2
3
4
5
{% highlight ruby %}
def foo
  puts 'foo'
end
{% endhighlight %}

highlight 的参数 (本例中的 ruby) 是识别所用语言。

行号

highlight 的第二个可选参数是 linenos 。使用了 linenos 会强制在代码上加入行号。例如：

1
2
3
4
5
{% highlight ruby linenos %}
def foo
  puts 'foo'
end
{% endhighlight %}

代码高亮的样式

要使用代码高亮，还需要包含一个样式表。例如 syntax.css 。它包含了和 GitHub 一样的样式，并且免费。

如果使用了 linenos ，可能还需要在 syntax.css 加入 .lineno 样式。

链接 link

如果要创建一组文档、博文、页面或文件的链接，使用 link 标签可以正确生成指定路径的永久链接。

1
2
3
4
{% link _collection/name-of-document.md %}
{% link _posts/2016-07-26-name-of-post.md %}
{% link news/index.html %}
{% link /assets/files/doc.pdf %}

还可以使用这个标签在MarkDown文件中创建一个链接：

1
2
3
4
[Link to a document]({% link _collection/name-of-document.md %})
[Link to a post]({% link _posts/2016-07-26-name-of-post.md %})
[Link to a page]({% link news/index.html %})
[Link to a file]({% link /assets/files/doc.pdf %})

博文链接（Post URL）

如果想使用某篇文章的链接，标签 post_url 可以满足需求。

1
{% post_url 2010-07-21-name-of-post %}

如果使用了子文件夹来组织博文，需要在路径中加入子文件夹：

1
{% post_url /subdir/2010-07-21-name-of-post %}

当使用post_url标签时，不需要写文件后缀名。

还可以用 Markdown 这样为文章生成超链接：

1
[Name of Link]({% post_url 2010-07-21-name-of-post %})

Gist

使用 gist 标签可以轻松的把 GitHub Gist 签入到网站中，对于公有和私有的 gist 均有效：

1
{% gist parkr/931c1c8d465a04042403 %}

也可以为 gist 设置文件名：

1
{% gist parkr/931c1c8d465a04042403 jekyll-private-gist.markdown %}

为使用 gist 标签，需要添加 jekyll-gist gem 到项目中。

永久链接 permalink

Jekyll 支持以灵活的方式管理网站的链接，可以通过 _config.yml 或 YAML 头信息 为每篇文章设置永久链接。

可以随心所欲地选择内建链接格式，或者自定义链接格式。永久链接的默认配置为 date。

永久链接的模板用以冒号为前缀的关键词标记动态内容，

模板变量

内建永久链接类型

页面和集合的永久链接

• 页面的默认模板是 /:path/:basename
• 集合的默认模板是 /:collection/:path
• 页面或集合文件的永久链接总能够在页面或者集合文件的头信息里重写覆盖。
• 给定的集合的永久链接能在集合配置中自定义设置。

含有反斜杠 / 的永久链接模板 pretty 会更新页面的永久链接，使其同样包含一个反斜杠： /:path/:basename/。

含有文件扩展名的永久链接模板 date 会更新页面的永久链接，使其同样包含文件扩展名： /:path/:basename:output_ext。

永久链接模板举例

比如文件名： /2009-04-29-slap-chop.textile

无扩展名永久链接

（Extensionless permalinks）

Jekyll 支持即不包含反斜杠也不包含文件扩展名的永久链接，但这需要网络服务端的额外支持才能正常工作。

当使用无扩展名永久链接时，写到硬盘上的输出文件依然会保留正确的文件扩展名（典型的比如，.html），所以网络服务端必须能够 map 那些没有文件扩展名的文件的请求。

无论 GitHub Pages 还是 Jekyll 内置的 WEBrick server 都能够正确处理这些请求，不需要任何额外工作。

Apache

Apache 网络服务端对内容协商（content negotiation）有着非常广泛的支持，而且能够通过在 httpd.conf 或者 .htaccess 文件中设置 multiviews 选项来处理无扩展名的 URLs：

1
Options +MultiViews

Nginx

try_files 指令允许指定一个文件列表搜索，用来处理请求。如果请求的 URL 的精确匹配未找到的的话，下列配置会让 nginx 搜索含有 .html 扩展名的文件。

1
try_files $uri $uri.html $uri/ =404;

分页功能 paginate

• 在 Jekyll 3 中，需要在 gems 中安装 jekyll-paginate 插件，并添加到 Gemfile 和 _config.yml 中。
• 在 Jekyll 2 中，分页是标准功能。

• 分页功能只支持 HTML 文件，不支持 Jekyll site 中的 Markdown 或 Textile 文件。

• 分页功能从名为 index.html 的 HTML 文件中被调用时才能工作。

开启分页功能

只需要在 _config.yml 里边加一行，指明每页该展示多少项目：

1
paginate: 5

这个数字是希望在生成的站点中每页展示博客数目的最大值。

指定分页页面的目标路径

1
paginate_path: "blog/page:num"

blog/index.html 将会读取这个设置，把它传给每个分页页面，然后从第 2 页开始输出到 blog/page:num, :num 是页码。

如果有 12 篇文章并且做如下配置 paginate: 5，Jekyll 会将前 5 篇文章写入 blog/index.html，把接下来的 5 篇文章写入 blog/page2/index.html，最后 2 篇写入 blog/page3/index.html。

在博客的头信息中设置 permalink 会造成分页功能的瘫痪。缺省设置 permalink 即可。

可用的 Liquid 属性

分页功能插件使得 paginator Liquid 对象具有下列属性：

分页功能遍历 posts 下的所有文章，而忽略定义在文章内的头信息中的变量。

不支持对“标签”和“类别”分页，也不支持任何文件集合，该功能被限制在 posts 中。

生成带分页功能的文章

使用已经 paginator 变量，列表展示文章。

在 HTML 文件中生成带分页功能的文章：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
---
layout: default
title: My Blog
---

<!-- 遍历分页后的文章 -->
{% for post in paginator.posts %}
  <h1><a href="{{ post.url }}">{{ post.title }}</a></h1>
  <p class="author">
    <span class="date">{{ post.date }}</span>
  </p>
  <div class="content">
    {{ post.content }}
  </div>
{% endfor %}

<!-- 分页链接 -->
<div class="pagination">
  {% if paginator.previous_page %}
    <a href="/page{{ paginator.previous_page }}" class="previous">Previous</a>
  {% else %}
    <span class="previous">Previous</span>
  {% endif %}
  
   <span class="page_number ">Page: {{ paginator.page }} of {{ paginator.total_pages }}</span>
    
  {% if paginator.next_page %}
    <a href="/page{{ paginator.next_page }}" class="next">Next</a>
  {% else %}
    <span class="next ">Next</span>
  {% endif %}
</div>

注意首尾页

Jekyll 不会生成文件夹 page1，所以如上代码在遇到 /page1 这样的链接时会出错。

下边的 HTML 片段能够处理第一页，为除当前页面外的每个页面生成链接。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{% if paginator.total_pages > 1 %}
<div class="pagination">
  {% if paginator.previous_page %}
    <a href="{{ paginator.previous_page_path | prepend: site.baseurl | replace: '//', '/' }}">&laquo; Prev</a>
  {% else %}
    <span>&laquo; Prev</span>
  {% endif %}

  {% for page in (1..paginator.total_pages) %}
    {% if page == paginator.page %}
      <em>{{ page }}</em>
    {% elsif page == 1 %}
      <a href="{{ paginator.previous_page_path | prepend: site.baseurl | replace: '//', '/' }}">{{ page }}</a>
    {% else %}
      <a href="{{ site.paginate_path | prepend: site.baseurl | replace: '//', '/' | replace: ':num', page }}">{{ page }}</a>
    {% endif %}
  {% endfor %}

  {% if paginator.next_page %}
    <a href="{{ paginator.next_page_path | prepend: site.baseurl | replace: '//', '/' }}">Next &raquo;</a>
  {% else %}
    <span>Next &raquo;</span>
  {% endif %}
</div>
{% endif %}

插件 _plugins/

在 GitHub Pages 使用插件

GitHub Pages 是由 Jekyll 提供技术支持的，考虑到安全因素，所有的 Pages 通过 --safe 选项禁用了插件功能，因此如果网站部署在 Github Pages ，那么插件不会工作。不过仍然有办法发布到 GitHub Pages，只需在本地做一些转换，并把生成好的文件上传到 Github 替代 Jekyll 就可以了。

安装插件

可以使用以下三种方式安装插件：

1. 在网站根下目录建立 _plugins 文件夹，插件放在这里即可。 Jekyll 运行之前，会加载此目录下所有以 *.rb 结尾的文件。

2. 在_config.yml文件，添加一个键为gems的新数组，其值为想要使用的gem插件的名字，例如：

   1
   2
    gems: [jekyll-coffeescript, jekyll-watch, jekyll-assets]
    # This will require each of these gems automatically.
   

   然后安装插件使用命令 gem install jekyll-coffeescript jekyll-watch jekyll-assets

3. 在 Gemfile 中的一个Bundler组里添加相关的插件，例如：

   1
   2
   3
   4
    group :jekyll_plugins do
      gem "my-jekyll-plugin"
      gem "another-jekyll-plugin"
    end
   

   然后需要从Bundler组中安装所有插件，使用命令bundle install

三种方式可以同时使用。

主题

Jekyll 包含有一个强大的主题系统，可以使用社区的模板和样式来定制自己的站点。

Jekyll 主题打包了布局文件、包含文件及样式表，也可以使用自己站点的内容去覆盖它们的默认内容。

安装主题

1. 若要安装一套主题，请先将该主题添加到站点的 Gemfile 中：

   1
    gem 'my-awesome-jekyll-theme'
   

2. 保存并应用 Gemfile 中相关的文件变化。

3. 执行命令行 bundle install 来安装主题。

4. 最后向站点的 _config.yml 中加入下列代码来启用主题：

   1
    theme: my-awesome-jekyll-theme
   

可以在站点的 Gemfile 中留有多套主题，但在 _config.yml 中只能选择一个来激活使用。

覆盖主题默认内容

Jekyll 主题含有主题默认的布局文件、包含文件和样式表，可以使用自己站点的内容去覆盖它们。

举个例子，如果选择使用一个具有 page 布局的主题，能通过在 _layouts 文件夹下创建一个属于自己的 page 布局文件(例如 _layouts/page.html)来覆盖当前主题的布局。

在下列文件夹中，Jekyll 会优先查看站点中的内容，然后查看主题的默认内容：

• /assets
• /_layouts
• /_includes
• /_sass

如果想要定位电脑上主题文件的位置，执行命令 bundle show 加上主题包的名称， 如： bundle show minima 命令来查询 Jekyll 默认主题包的位置， 然后从返回的路径拷贝想要重写的文件到网站根目录中。

创建主题

附加功能

根据使用 Jekyll 的不同方式，Jekyll 允许安装一些可选的附加功能。

数学支持

使用 Kramdown 时可以选择使用由 MathJax 提供的 LaTeX 格式到 PNG 格式的数学区块渲染器。

具体细节可查阅 Kramdown 文档中的 math blocks (数学区块) 以及 math support (数学支持) 部分。

使用 MathJax 需要设置引用相关的 JavaScript 或 CSS 资源来渲染 LaTeX, 例如：

1
<script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>

GitHub Pages

Github Pages是面向用户、组织和项目开放的公共静态页面搭建托管服务，站点可以被免费托管在 Github 上，可以选择使用 Github Pages 默 认提供的域名github.io或者自定义域名来发布站点。

两种部署方式：

用户和组织的站点

github仓库命名：username.github.io 。

仓库中master分支里的文件将会被用来生成 Github Pages 站点。

Github Pages 初始被设置部署在username.github.io 子域名上，即使使用自定义域名，仓库还需要这样命名。

项目的站点

项目的站点文件存放在项目本身仓库的 gh-pages 分支中。

生成的站点被部署到用户站点的子目录上，例如 username.github.io/project （除非指定自定义域名）。

源文件必须在根目录，GitHub Pages 重载了Site Source配置的默认值，如果将文件放在除了根目录之外的任何位置，都可能导致网站不能正确构建。

部署方法

打 赏

微信支付

支付宝

• Previous
  Django学习整理
• Next
  Liquid基本语法