JEKYLL DOCUMENTS

• GETTING STARTED
• QuickStart
  • Installation
• Ruby 101
  • Gems
  • Gemfile
  • Bundler
• CONTENT
• Front Matter
  • Predefined Global Variables
  • Custom Variables
  • Predefined Variables for Posts
• Collections
  • Setup
  • Add content
• SITE STRUCTURE
• Directory Structure
• Liquid
  • Filters
  • Tags
    • Includes
    • Code snippet highlighting
      • Line numbers
      • Stylesheets for syntax highlighting
  • Links
    • Linking to pages
• Variables
  • Global Variables - References

GETTING STARTED

QuickStart

Jekyll is a static site generator.

使用标记语言键入文本，用布局创建静态网站，然后可以决定如何显示内容，调整网站 URL等。

Installation

Jekyll is a Ruby Gem that can be installed on most systems.

安装前的准备 (Requirements)。

1. 安装 Ruby 开发环境。
2. 安装 Jekyll 和 bundler gem。

   gem install jekyll bundler
   # 之前安装过：gem update jekyll
   

3. 创建网站在 ./myblog。

   jekyll new myblog
   # 强制执行：--force
   

4. 切换目录。

   cd myblog
   

5. 搭建网站并让它运行在本地服务器。

   bundle exec jekyll serve
   # 自定义HOST：--host=HOST
   # 自定义PORT：--port=PORT
   

6. 浏览 http://localhost:4000。

Ruby 101

Jekyll is written in Ruby.

简单了解下 Ruby 的相关技术。

Gems

A gem is code you can include in Ruby projects. Gems 有这些功能：

• 将 Ruby object 转换成 JSON
• 分页 （Pagination）
• 与 APIs 交互，比如 GitHub
• Jekyll 本身就是 gem，包括很多 Jekyll plugins 如 jekyll-feed, jekyll-seo-tag 和 jekyll-archives 也是

Gemfile

Gemfile 是记录着网站必需的 gem 的一个列表。对于一个比较简单的网站它可能长这样：

source "https://rubygems.org"

gem "jekyll"

group :jekyll_plugins do
  gem "jekyll-feed"
  gem "jekyll-seo-tag"
end

Bundler

Bundler installs the gems in your Gemfile.

虽然不是必需的，但它可以确保你在不同的环境中，运行着相同版本的 Jekyll 和 plugins，所以还是安装比较好。

关于如何使用 Bundler 戳这里。

CONTENT

Front Matter

Any file that contains a YAML front matter block will be processed by Jekyll as a special file. 简单说下 Front Matter。

---
layout: post
title: Blogging Like a Hacker
---

在 --- 之间，你可以预定义变量，甚至创造自定义变量。

These variables will then be available to you to access using Liquid tags both further down in the file and also in any layouts or includes that the page or post in question relies on.

Predefined Global Variables

There are a number of predefined global variables that you can set in the front matter of a page or post.

Custom Variables

You can also set your own front matter variables you can access in Liquid. For instance, if you set a variable called food, you can use that in your page:

---
food: Pizza
---

<h1>{{ page.food }}</h1>

Predefined Variables for Posts

These are available out-of-the-box to be used in the front matter for a post.

Collections

Collections are a great way to group related content like members of a team or talks at a conference.

Setup

先在 _config.yml 定义集合，如：

collections:
  - staff_members

在这个例子 collections 被定义为一个没有额外元数据的序列 (i.e array)，并定义给每一个集合。可以将 collections 定义为映射 (i.e hashmap) 而非序列，来给集合指定元数据，然后反映出额外的字段 (filed)：

collections:
  staff_members:
    people: true

Add content

创建对应文件夹 (e.g.<source>/_staff_members) ,添加文档。如果头部信息存在则处理，所有后面的内容都属于文档的 content 属性。如果没有头部信息，Jekyll 会认为这是一个 static file 并且内容不会经过进一步的处理。如果有头部信息，Jekyll 则将文件内容处理成期望的输出。

不管有没有头部信息，Jekyll 都会写进宿 (destination directory) 目录 (e.g. _site) 仅当 output: true 被设置进集合的元数据。

举个例子，这是如何添加一份 Staff 名单到上面设置的集合，文件名为 ./_staff_members/jane.md 有如下内容:

---
name: Jane Doe
position: Developer
---
Jane has worked on Jekyll for the past *five years*.

注意不管被当作 合法文件名格式的 Posts 会被标记处理，即使它们不包括头部信息

SITE STRUCTURE

Directory Structure

Liquid

Jekyll uses the Liquid templating language to process templates.

简而言之，输出内容： {{ variable }}；执行逻辑：{% if statement %}。（注）

想了解更多关于 Liquid 的信息，请查看 Liquid 官方文档。

除了 Liquid 官方文档中的，Jekyll 还额外添加了一些 Filters 和 Tags 帮助你搭建网站。

Filters

所有滤器（Filter）都能在这查看。标准 Liquid 滤器。

为了让一些常见的需求更简单，Jekyll 本身也添加了一些方便的滤器，你也可以通过插件来创建自己的滤器。

Tags

所有标签 (Tags) 都能在这查看。Jekyll 内置了一些标签帮助你搭建网站，你也可以通过插件来创建自己的滤器。

Includes

如果你有会重复利用的页面代码片段，include 可以完美地提高站点地可维护性.

Code snippet highlighting

感谢 Rouge提供给 Jekyll 超过 100 种语言的语句高亮，Rouge 是 Jekyll 3 和以上版本默认使用的语句高亮。

用语句高亮渲染代码块，如下所示：

{% highlight ruby %}
def foo
  puts 'foo'
end
{% endhighlight %}

def foo
  puts 'foo'
end

highlight 的参数 (在上例中为 ruby) 是语言标识符，查看 Rouge wiki 的”short name”，寻找合适的标识符。

Line numbers

highlight 的第二个参数是可选的，叫作 linenos，作用是强制高亮代码并包含行号，如下所示：

{% highlight ruby linenos %}
def foo
  puts 'foo'
end
{% endhighlight %}

1
2
3
def foo
  puts 'foo'
end

Stylesheets for syntax highlighting

为了让高亮能显示，你还要包含一个高亮样式表，对于 Pygments 或 Rouge 你可以使用 Pygments 的样式表，you can find an example gallery here or from its repository.

复制 CSS 文件 (如 native.css) 到你的 CSS 目录并导入这些语句样式到你的 main.css 中：

@import "native.css";

Links

Since Jekyll 4.0 , you don’t need to prepend link and post_url tags with site.baseurl.

Linking to pages

链接到文章

Variables

Jekyll makes a variety of data available via the Liquid.

Global Variables

此外还有 Site Variables 和 Page Variables，以及 Paginator 的变量。太多了，不复制了。

References

1 JEKYLL 文档

2 JEKYLL 中文文档