# jekyll

jekyll 的使用笔记

# 概述

jekyll 是基于 ruby 的静态博客生成器. 结合 github pages 可以实现快速部署个人静态博客.

# 快速入门

1. 环境安装

   • brew install ruby 安装 ruby,mac 默认安装了 ruby 环境.
   • curl -L get.rvm.io | bash -s stable 安装 ruby 版本管理工具 rvm
   • gem install jekyll bundler 安装 jekyll,bundler

2. 新建 jekyll 博客.

   # 在家目录创建 blog 文件夹
   mkdir ~/blog
   
   # 在 blog 目录下初始化 jekyll_demo
   jekyll new ~/blog/jekyll_demo
   
   # 在 jekyll_demo 目录下安装依赖包
   bundle install
   
   # 编译本地 jekyll 博客
   jekyll serve
   

   访问 http://localhost:4000即可查看到 jekyll 默认主题 minima 生成的静态页面.

jekyll serve 编译后的目录结构如下.

|-- Gemfile
|-- Gemfile.lock
|-- _config.yml
|-- _posts
|-- _site
|-- about.md
`-- index.md

各文件含义

详见 jekyll 目录结构

# 创建新文章

在 _posts 目录下新建名为 <site.time | date: '%Y-%m-%d' >-jkeyll.md的文件. 添加如下内容.

---
title: jekyll
tags: jekyll ruby
---

jekyll demo
===

**前言: 讲解 jeyll 的使用**
---

today is <site.time | date: '%Y-%m-%d' >

重新编译jekyll serve访问 http://localhost:4000 即可看到 如下内容

创建文件需要符合三点.

1. 文件名符合 <YYYY-MM-DD>-<filename> 的格式. 文件后缀取决于你用的文本类型例如 .md 表 markdown 类型.

2. 文件开头为

   
   ---
   title: jekyll
   tags: jekyll ruby
   ---
   

   符合 front matter 格式. 该格式基于 YAML 语法.用来定义文章中的变量,给 jekyll 解析.例如 title 变量值会被编译为对应 html 的 title 标签中.

3. 文章的内容

   jekyll demo
   ===
   
   **前言: 讲解 jeyll 的使用**
   ---
   
   today is {{site.time | date: '%Y-%m-%d' }}
   

   符合对应的语法格式, jekyll 通过文件名后缀选择对应的转义引擎, 例如 .md 文件,默认使用 kramdown 转义为 html. 可以看到文件内容除了支持标准的 markdown 文法,还支持模板, jekyll 使用 liquid 来转义模板语法.

# 概念建立

通过以上实例我们可以直接在 _post 文件夹下 建立符合格式的文章,重新编译即可创建博客. 但是这只是最基础的内容,对于常见的博客我们可能有如下需求.

• 更换博客主题(默认主题太简陋)
• 实现索引文件(用来分类显示所有博文)
• 添加评论系统
• 添加博文统计系统
• 个性化配置

以上的需求我们会逐一讲解.

# 更换主题

使用 jekyll new <path> 命令默认使用的是 minima 主题. 更换主题的步骤如下.

1. 去 jekyll-theme 选择一个你喜欢的主题 也可参看知乎 简洁明快的 jekyll 模板
2. 进入主题的 github 页面,按照官方说明进行配置即可

简要概述就是把 _post 中的内容拷贝到主题对应文件中. 同时按照主题要求配置好自己个人信息即可.

# 静态服务器的工作流

jekyll 整个处理流程,步骤如下.

1. 读取_config.yml 配置项,确定 jekyll 引擎的工作, 空文件会利用默认配置进行处理.
2. 在工作目录全局递归查找文件头符合 front matter tags 格式的内容.
3. 模板处理

   1. jekylll 处理模板变量

      • site 包含整个静态网站信息,所有页面均可引用
      • page 包含该静态页面信息,可在页面中备引用
      • post 提交集合的变量

   2. liqiud 利用该模板将变量替换为对应内容.除了简单的变量替换模板还提供如下功能.

      • liqiud tags
      • liqiud variable
      • liqiud filter 实现内容过滤,

   3. 内容格式转换 使用 kramdown 将 markdown 等文本内容转换为 html 标签.

   4. 布局排版 将文章写入设定的 layout 模板,或默认模板的 <content> 中, 递归 layout 流程 递归 layout

   5. 文件写入 将排版后的文档按照文件路径或 permalink 配置项写入 _site 目录下

# 常见错误

误解布局先后顺序

1. liquid 解析变量在 jekyll 模板转化之前. 可以需要解析的模板变量放入 front formatter 之中

忽略文件类型影响

内容的编译是基于文件类型完成的. 若在 html 文件中包含 markdowm 类型文件. 解析器不会渲染.可以直接使用 html 替换对应文本内容即可

复合使用

例如模板的颜色高亮.使用如下结构

{% highlight javascript %}
console.log('alert');
{% endhighlight %}

无需在高亮内容中再使用 markdown 语法. 直接编写需要高亮的内容即可. 牢记静态网站的编译顺序.

liqiud 变量 -> 内容解析器 -> front formatter

# 学习内容

1. 全局配置文件
2. liquid 模板语法
3. 页面配置 front formatter
4. jekyll 常用特性
   • layout
   • premalink
   • ...

# 常用设置

# 配置 404 页面

只需在工作目录的根目录添加 404.md 或 404.html 即可. 或者直接将想作为 404 返回界面的文件的 pernalink 设置为 /404.html 即可. 若将今天页面布置到 apache 或 ngnix 服务器上,直接参看官方配置即可.

# 自定义渲染模板

1. 创建自定义模板

在工作目录的的 _layouts 目录中,新建 default.html. 可以利用模板变量定义引用.核心配置 * 主内容去使用 <content>进行替换 * title 利用 <page.title> 替换

2. 模板引用

在需要使用该模板的页面 fornt formatter 中配置 layout 为 _layouts 下的文件名.

3. 重新编译内容即可

其他

参见 jekyll tutorials

# 快速入门

前提保证安装了 ruby 和 rubyGems 的保管理工具.

1. 环境安装

sudo gem isntall jekyll

# 创建新 blog
jekyll new blog

# 切换到主目录
cd myblog

# 编译和创建服务
bundle exec jekyll serve

# jekyll 原理

项目文件 -> 渲染模板 -> 格式转换 -> 静态网站(html,css,js)

详细步骤:

1. site 变量,收集所有静态页面定义的变量.
2. liquid 利用该模板解释文档中的内容
   • liquid

# 渲染模板支持的功能

templates 模板

variable

页面收集功能.当内容非提交或主页面时. 利用 collections 归纳页面. 例如按照标签,时间线等.

# collections 使用

利用 collection 来对文章进行分类

1. 去 _config.yml 文件添加配置,注意文件名称前加 _ 才可引用.

collections:
  my_collection:
    output: true
    permalink: /:collection/:name

也可选择其他的映射方式 collections 映射

2. 在更目录创建对应的 _my_collection 的文件夹

实际上 _posts 就是 jekyll 内部默认的 collections .

自定义变量放在 _data 利用 site.data.<file_name> 进行引用 支持 json,yaml,csv 三种文件类型.

# 本地文件和 url 映射原理

默认映射方式 /:categories/:year/:month/:day/:title.html 配置路径映射的方式有两种.

• 在每个文件中的 fromt matter 中设置 permalink 属性
• 在 _config.yml 中进行配置,参见 config 和 collections

前者的设置会覆盖全局设置.常用技巧

• 忽略文件后缀,会将文件作为 index.html 放入目录

本地的文件类型分为三种.

• pages 直接加载的静态页面或内容
• 定义在 collections 模块中的内容
• 属于 post 目录下的内容

应为对于 post 文件下的内容命名有强约定,而对于其他两种类型没有此约定. 所以在全局设置 permalink 时对不同文件类型的表示有区别.

例如在全局环境下配置 permalink: data

• _posts 下的文件 url 为 /:categories/:year/:month/:day/:title.html
• collection 和 page 为 /:title.html

# 待度清单

• [ ] jekyll 基本入门
• [ ] 博客迁移 blog migrations
• [ ] 可以包含自定义 sass 文件 asset

语言使用 ruby.

.
├── _config.yml
├── _data
|   └── members.yml
├── _drafts
|   ├── begin-with-the-crazy-ideas.md
|   └── on-simplicity-in-technology.md
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2007-10-29-why-every-programmer-should-play-nethack.md
|   └── 2009-04-26-barcamp-boston-4-roundup.md
├── _sass
|   ├── _base.scss
|   └── _layout.scss
├── _site
├── .jekyll-metadata
└── index.html # can also be an 'index.md' with valid YAML Frontmatter

文件作用.

核心配置文件 _config.yml 决定 jekyll 的编译逻辑. 常用配置如下. http://jekyllrb.com/docs/configuration/.

# 编辑方法

1. _posts 存放已编写好的内容
2. _drafts 存放草稿

# post 文件规则

• 文件名 year-month-day-title.markup

  • year 四位格式
  • month,day 2 位格式
  • markup 问文件格式

• 文件开头符合 yaml front matter

  • 利用 --- 划分题头和正文
  • 题头用来定义模板需要的默认变量,例如 title 等
  • 文件头定义字段可利用 liquid 模板语法引用.
  • 文件头也可为空,但必须保留 --- 的结构,给 skeyll 解析
  • 注意文本格式不要是 bom 的 utf-8,特别是在 windows 下

• 文件内容,支持如下格式

  • markdown
  • textile

文件开头提供如下的全局变量给 jekyll 去使用.

利用 jekyll serve --unpublished 或 --drafts 来编译草稿或私有文件

文件引用路径可以包含变量

site.url 在编译时会变为项目根路径

![]({{site.url}}/path/file)

标注 post 文件格式如下

    ---  ---> YAML 格式的题头
    layout: post  --> 布局模式为 post
    title:  "test skeyll" --> 文章主题
    date:   2015-11-17 16:16:01 -0600 --> 文章创建时间
    categories: jekyll update -->文章分类
    ---

    ---> 文章正文

    You’ll find this post in your `_posts` directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run `bundle exec jekyll serve`, which launches a web server and auto-regenerates your site when a file is updated.

    To add new posts, simply add a file in the `_posts` directory that follows the convention `YYYY-MM-DD-name-of-post.ext` and includes the necessary front matter. Take a look at the source for this post to get an idea about how it works.

文件内容的引用使用assets 或 downloads 文件夹. 为了防止应用路径丢失可以在引用前加入<site.url> 变量. 若加载资源一直属于根目录下则直接使用/path/source 即可.

![test]({{site.url}}/assets/test.jpg)

可以直接在内容区域使用模板,例如想在文章结尾列出所有文章.

<ul>
  {% for post in site.posts %}
    <li>
      <a href="{{ post.url }}">{{ post.title }}</a>
    </li>
  {% endfor %}
</ul>

内部模板引擎会将所有文章逐一列出.

# 插件体系

plugins

注意由于 github pages 中使用的是安全模式进行的编译,意味着你不能使用自定义插件进行编译. 基于此建议本地编译,在 githubpage 上传编译后的内容.

插件安装的三种方式

• 在 _plugins 目录下放置插件
• 在 _config.yml 文件中添加插件

plugins: [[jekyll-coffeescript, jekyll-watch, jekyll-assets]

利用 gem istall jekyll-coffeescript jekyll-watch jekyll-assets 安装插件

• 在 Gemfile 中添加相关插件

group :jekyll_plugins do
   gem "my-jekyll-plugin"
   gem "another-jekyll-plugin"
 end

使用 bundle install 进行安装.

这三种方式可以被同时使用.插件一般分为五大类.

1. generators

定义一个符合自己规则的编译规则. 利用 generators 可以在每个文件中添加自定义内容.

2. Converters

选择新的转换器来转换文档内容

3. Commands

定义命令在文章中引用.

4. Tags

自定义标签在模板中使用

5. Hooks

利用钩子在引擎执行的各个阶段实现自动化控制.

导航

• 提取数据放入 _data 目录
• 在题头循环导出数据

1. 利用 data 定义分类用模板进行显示.

docs_list_title: Docs
docs:

- title: Introduction
  url: introduction.html

- title: Configuration
  url: configuration.html

- title: Deployment
  url: deployment.html

若要产生排序的列表使用过滤器.

使用模板语言进行过滤.

# 模板原理

利用 liqiud 进行模板解析. 利用题头进行变量定义. 模板应用方法.

变量

--- --> 利用 yaml 题头进行变量定义
test:hello
---

**<page.test>** --> 此处解析变量,注意变量属于 page 的属性

若想添加原始页面,直接在编译生成的静态网站中建立文档即可. 或者直接在在资源的根目录或子目录,创建 html 文件. 或题头符合 YAML 规范的 mark 文档,都会直接被编译到静态文件根目录 下的相应位置. jekyll 编译器会遍历根目录下内容进行处理. 若存在非 jekyll 直接规定的文件夹则直接编译到静态网站的相应位置. 同时会根据文件的类型进行默认的编译.利用 permalink 属性控制 markdown 等文档类型的编译位置.

# 坑

ruby 版本不够

1. 使用 brew 安装 rvm ,ruby 版本管理工具

curl -L get.rvm.io | bash -s stable
source ~/.rvm/scripts/rvm

2. 使用 rvm 管理 ruby 安装包

# 验证 rvm 安装成功
rvm -v

# 列出所有 ruby 安装版本
rvm list known

# 安装 ruby,
rvm install 2.1.4

# 使用某版本 ruby 并设为默认
rvm use 2.1.4 --default

# 查看已安装版本
rvm list

# 卸载已安装版本
rvm remove 2.1.4

# 查看安装镜像
gem source

# 跟换镜像
gem update --system
gem uninstall rubygems-updates
gem sources -r http://rubygems.org/
gem sources -a http://rubyg.taobao.org

不理解 ruby 生态

• gem 是 ruby 环境的包管理工具
• gemfile 是 ruby 安装配置文件
• bundle 也是包管理工具,但是比 gem 高级,支持批量安装
• 使用 rvm 管理 ruby 版本
• jekyll 是基于 ruby 的静态生成器
• jekyll 插件可以利用 bundle 来安装依赖

jekyll-compose

# 颜色高亮

gem install rouge

highlighter: rouge
 

# 资料

自动加载