lxjwlt's blog

Jekyll on Win7

老早就想用 github-pages 创建一个博客,于是这几天研究了一下 Jekyll,看了 Jekyll 英文文档和相关的博文,感觉英文的文档看起来很吃力,所以搭建好这个博客之后,觉得应该整理一下这方面的资料,总结安装和使用过程中遇到的问题,以备日后不时之需,也希望对大家有所帮助。

首先推荐一篇博文——搭建一个免费的,无限流量的Blog----github Pages和Jekyll入门

上述博文介绍如何搭建一个具备基本功能的 github-pages 博客。读完通篇文章,我有个疑惑——搭建一个 github 博客不需要本地安装 Jekyll ,那安装 Jekyll 有什么用呢?后来才了解到,为了方便本地调试,而不需要每次都 push 到 github 中来查看页面效果——据说 github-pages 更新有延迟,所以安装本地 Jekyll 是有必要的。

下面会介绍到 Jekyll 的安装和基本使用,这些内容都是基于 win7 环境

安装

安装 Jekyll 前需要先安装 RubyRuby DevKit,下载地址:http://rubyinstaller.org/downloads/

安装完 Ruby 并添加进 PATH 后,解压 Devkit 安装包,进入 Devkit 解压文件根目录下,对其初始化:

ruby dk.rb init

初始化成功后,控制台会提示fix config.yml file,这时用文本编辑器打开 Devkit 解压文件根目录下的config.yml文件,并按提示在文本底部添加 Ruby 的安装路径,如下:

# This configuration file contains the absolute path locations of all
# installed Rubies to be enhanced to work with the DevKit. This config
# file is generated by the 'ruby dk.rb init' step and may be modified
# before running the 'ruby dk.rb install' step. To include any installed
# Rubies that were not automagically discovered, simply add a line below
# the triple hyphens with the absolute path to the Ruby root directory.
#
# Example:
#
# ---
# - C:/ruby19trunk
# - C:/ruby192dev
#
---
- F:/Ruby200-x64

然后在控制台中继续输入(此时路径仍是解压包根目录)

ruby dk.rb install

如果没有出错,就可以安装Jekyll了:

gem install jekyll

gem install安装时是不会显示任何东西的,这样会让人误以为安装没有开始进行,因此可以添加大写的参数V,让它显示安装日志:

 gem install jekyll -V

接着,检测是否成功安装:

jekyll -v

如果返回版本号,如jekyll 1.2.0,说明成功安装。

使用

初始化

Jekyll 安装成功后,在任意目录下,创建一个初始的模板:

jekyll new myblog

这样该目录下会自动创建一个 myblog 文件夹,其中包含 Jekyll 最基本的架构:

.
├── _config.yml
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   └── 2013-09-11-welcome-to-jekyll.markdown
├── css
|   ├── main.css
|   └── syntax.css
└── index.html

此时可以开启本地服务器来查看该页面,将路径指定到 myblog 目录下后运行:

jekyll serve

如果没有出错,用浏览器打开http://localhost:4000就可以在本地查看该页面了。

如果控制台提示以下错误:

  Conversion error: There was an error converting '_posts/XXXX-XX-XX-XXXXX.md'

该错误是由于没有安装pygments所导致的,可以选择关掉此项功能:打开_config.yml文件,将其中的pygments项设为false。或者参考以下几篇文章来安装pygments:

写博文

首先,博文格式有几点需要注意的:

所谓的 YAML front-matter ,是指以---开头,以---结尾的一种形式,用于给文章添加一些有用的信息,如类别、标签、摘要、标题等等,形式如下:

---
layout: post
title: 我的第一篇文章
category: front-end
excerpt: '这是我的第一篇博文的摘要!!'
---

其中layout是为该博文指定一个HTML模板,模板统一放在_layout文件夹下,默认模板有default.htmlpost.html

这些 YAML 格式的信息都可以用 Liquid 语法写入HTML文件中,当页面解析时,会自动获取这些值,填充进页面中,后面再深入说明。

注意,即使不为博文添加任何信息,也需要按 YAML 形式开头:

---
---

写好的博文放入_post文件夹中,Jekyll 后台启动后会自动将它解析并添加入页面中。

如果博文中有中文编码,在运行jekyll serve后可能会提示如下错误:

 invalid byte sequence in GBK

解决方法:

<ruby path>\lib\ruby\gems\2.0.0\gems\jekyll-1.2.0\lib\jekyll\convertible.rb文件中的:

 self.content = File.read(File.join(base, name))

改为:

 self.content = File.read(File.join(base, name), :encoding => "utf-8")

内部构造

模板

默认模板中default.html构造了页面的基本结构,同时负责引入了css文件和js文件等,大致结构如下:

<!DOCTYPE html>
<html>
    <head></head>
    <body>
        <div class='header'></div>

        {{ content }}

        <div class='footer'></div>
    </body>
</html>

需要了解的是,模板中都会有{{ content }},当文件套用模板时,该文件的内容是填充到{{ content }}中。

首页

默认首页为根目录下的index.html文件,结构如下:

---
layout: default
title: Your New Jekyll Site
---

<div id="home">
  <h1>Blog Posts</h1>
  <ul class="posts">
    {% for post in site.posts %}
      <li><span>{{ post.date | date_to_string }}</span> &raquo; <a href="{{ post.url }}">{{ post.title }}</a></li>
    {% endfor %}
  </ul>
</div>

以上编码的作用是在首页中创建一个博文链接的列表。

其中{% for post in site.posts %}是 Liquid 语法结构,它的作用是对全部的博文做一个遍历,每次遍历到的对象用post来表示;

{{ post.date }}是博文的分布时间,默认从博文的命名中获取,也可以在博文开头的 YAML 中随意定义,其后的date_to_string是一个参数,用于将该时间转换成一种简化的形式,如:14 Sep 2013。如果喜欢2013-9-14这种格式,可以使用另一种参数:"%Y-%m-%d"

{{ post.date | "%Y-%m-%d" }}

{{ post.url }}是博文的链接。

任何在博文 YAML 中定义的信息都可以用{{ post.XXXXX }}的形式填充到页面中。

github-pages

jekyll new语句初始化的文件可以直接在本地服务器正常调试,但如果想在 github-pages 中正常使用,还需要进行一些设置:

  1. _config.yml文件中添加baseurl选项,并设置为/project-name,比方说 github 上的项目名为‘myFirstBlog’,则该选项应设置为/myFirstBlog
  2. 在页面引用的所有 JS 或 CSS 文件的链接开头添加{{ site.baseurl }},形如:{{ site.baseurl }}/path/to/main.css
  3. 给博文链接开头添加{{ site.baseurl }},如:{{ site.baseurl }}{{ post.url }}

这样,github-pages 上就能正常使用了。

然而这时候通过本地服务器调试页面时,却发现不能如常使用了,这是由于“设置了baseurl,同时改动了一些链接”所导致的。因此进行了以上的设置后,每次打开本地服务器调试页面时,都需要将baseurl设置为空字符:

jekyll serve --baseurl ''

实用技巧

相关链接

官方文档

博文教程