像黑客一样写博客——Jekyll入门

原文：http://www.soimort.org/tech-blog/2011/11/19/introduction-to-jekyll_zh.html

Jekyll 是一个简洁的、特别针对博客平台的 静态网站 生成器。它使用一个模板目录作为网站布局的基础框架，并在其上运行 Textile 、 Markdown 或 Liquid 标记语言的转换器，最终生成一个完整的静态Web站点，可以被放置在Apache或者你喜欢的其他任何Web服务器上。它同时也是 GitHub Pages 、一个由 GitHub 提供的用于托管项目主页或博客的服务，在后台所运行的引擎。

你可以去 这里 围观一些现有的使用Jekyll搭建的网站。本站（ www.soimort.org ）同样亦是基于Jekyll构建。

如果有任何问题，请加入 官方邮件组 的讨论，或访问Freenode上的IRC频道 #Jekyll （chat.freenode.net）。

本中文入门教程由 Mort 基于 Jekyll的官方Wiki 等网页内容翻译整理并维护。

为何要使用静态网站生成器（Static Site Generators）？

不同于 WordPress 这类博客平台（以及其他众多流行的CMS内容管理系统）在服务器端执行PHP等语言的动态框架、访问SQL数据库并动态产生Web页面的工作方式，静态网 站生成器的原理十分简单：将所有的页面、布局和帖子集合在一起，预先生成静态的站点。对于动态内容并非必要的站点——例如个人博客，静态网站生成器这样做 有几个明显的优势：

快速访问和弱服务器需求

静态HTML页面的载入速度理所当然地更快——因为它无需在服务器端执行任何代码。同时，这还大大地减轻了服务器的压力。

高安全性

基于与上述相同的理由，静态页面有着与生俱来的安全性。不像WordPress或者其他任何动态的框架，静态站点本身并不存在安全漏洞的问题。

版本控制

你无需通过WordPress来维护一整个复杂的数据库——静态站点的内容完全仅由文件系统中独立的目录和文件构成，这意味着你不但可以使用Shell、grep、sed、awk这些传统的Unix工具对它们执行操作和维护，更可以使用 Git 这样的分布式版本控制系统来管理它们，并且享受版本控制所带来的一切好处，如同维护任何软件项目的源代码库一样。你甚至可以重新生成以前任意时间点的整个网站！

简单部署

一旦静态网站生成以后，任何Web服务器都能够轻易地部署静态站点，而无须在服务器端安装配置其他任何多余的东西。你所需要做的仅仅是通过git、 rsync甚至ftp简单地上传文件到你的托管服务器。相比之下，WordPress博客的维护显得复杂得多，你可能需要在你的开发服务器和托管服务器上 安装、配置一整套LAMP+WordPress平台，并经常性地升级版本和维护。这是个繁重的技术活。

文本编辑器和自由格式书写

也许你不这么认为，但是作为一个hacker而言，在浏览器中一个300x300的文本区里码字写博客并非一件很酷的事情——如果你使用 Jekyll这样的静态网站生成器，你就可以用你喜欢的任何文本编辑器（vi、emacs……），用你习惯的标记语言以书写文本文件的方式来直接写博客文 章（就好像你平常写代码一样），避免了使用那些简陋和功能有限的Web界面。

1. 安装

Jekyll使用动态脚本语言 Ruby 写成。请首先 下载并安装Ruby（中文） 。

在使用Jekyll之前，你可能想要对Ruby语言有一些初步了解（非必需）。推荐阅读官方网站上的 20分钟体验Ruby（中文） 。

安装Jekyll的最好方式是通过RubyGems：

$ gem install jekyll

Jekyll依赖以下的gems模块： liquid 、 fast-stemmer 、 classifier 、 directory_watcher 、 syntax 、 maruku 、 kramdown 、 posix-spawn 和 albino 。它们会被gem install命令自动安装。

如果你在gem的安装过程中遇到了问题，你可能需要安装用于在Ruby 1.8上编译扩展模块的头文件。在Debian系统上使用如下命令：

$ sudo apt-get install ruby1.8-dev

在Red Hat / CentOS / Fedora平台上则是：

$ sudo yum install ruby-devel

在 NearlyFreeSpeech 上你需要：

$ RB_USER_INSTALL=true gem install jekyll

如果你在Windows平台上看到如下错误提示信息： Failed to build gem native extension ，你可能需要安装 RubyInstaller DevKit 。

在OS X上，你可能需要升级你的RubyGems：

$ gem update --system

LaTeX转换到PNG

Maruku 内置可选的转换LaTeX格式到PNG图片的支持。它通过0.6版的blahtex进行渲染，这和 dvips 同样都必须存在于你的$PATH环境变量中。

（注意： remi的Maruku分支 并不使用修正的 dvips 路径，如果你需要修改它的话。）

RDiscount

如果你想用 RDiscount 取代 Maruku 作为你的Markdown标记语言转换引擎，只需确认安装：

$ gem install rdiscount

并通过以下命令行参数执行Jekyll：

$ jekyll --rdiscount

或者也可以在你站点下的 _config.yml 文件中加入以下配置，以便以后每次执行时不必再指定命令行参数：

markdown: rdiscount

RedCloth

若要使用Textile标记语言，需要安装相应的转换引擎 RedCloth 。

$ gem install RedCloth

Pygments

若要通过 {% highlight %} 标签在帖子中嵌入语法高亮的代码，那么需要安装 Pygments 。

在OS X Leopard和Snow Leopard平台上：

它已经包含在了Python 2.6的预安装包当中：
$ sudo easy_install Pygments

在OS X平台上（使用MacPorts）：

$ sudo port install python25 py25-pygments

在OS X平台上（使用Homebrew）：

$ brew install python
# export PATH="/usr/local/Cellar/python:${PATH}"
$ easy_install pip
$ pip install --upgrade distribute
$ pip install pygments

注意：Homebrew并不会为你自动创建可执行文件的符号链接。如果使用Homebrew默认的Cellar目录位置和Python 2.7，请确保你已添加 /usr/local/Cellar/python 到你的 PATH 变量中。

在Arch Linux平台上：

$ sudo pacman -S python-pygments
$ sudo easy_install-3.2 Pygments

或选择使用python2版本的pygments：（不推荐）
$ sudo pacman -S python2-pygments
$ sudo easy_install-2.7 Pygments
注意： python2版本的pygments可执行文件名为 pygmentize2 ，而Jekyll所调用的可执行文件是 pygmentize 。你应当创建一个指向pygmentize的符号链接 # ln -s /usr/bin/pygmentize2 /usr/bin/pygmentize ，或者直接选择使用Python 3版本的pygments。

在Ubuntu和Debian平台上：

$ sudo apt-get install python-pygments

在Fedora平台上：

$ sudo yum install python-pygments

在Gentoo平台上：

$ sudo emerge -av dev-python/pygments

2. 使用

一旦Jekyll安装成功后，搭建一个Jekyll站点通常包括下面几步：

  1. 设定站点的基本结构，使用HTML和Liquid模板语言创建网页布局。
  2. 创建一些帖子，或者从你以前的博客平台导入。
  3. 在本地测试站点，查看效果。
  4. 部署你的网站。

基本结构

Jekyll从核心上来说是一个文本转换引擎。该系统内部的工作原理是：你输入一些用自己喜爱的标记语言格式书写的文本，可以是Markdown、 Textile或纯粹的HTML，它将这些文本混合后放入一个或一整套页面布局当中。在整个过程中，你可以自行决定你的站点URL的模式、以及哪些数据将 被显示在页面中，等等。这一切都将通过严格的文本编辑完成，而生成的Web界面则是最终的产品。

一个典型的Jekyll站点通常具有如下结构：

.
|-- _config.yml
|-- _includes
|-- _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
`-- index.html

以下是每部分功能的简述：

_config.yml

保存Jekyll配置的文件。虽然绝大部分选项可以通过命令行参数指定，但将它们写入配置文件可以使你在每次执行时不必记住它们。

_includes/

该目录存放可以与_layouts和_posts混合、匹配并重用的文件。Liquid标签{% include file.ext %}可以用于嵌入文件_includes/file.ext。

_layouts/

该目录存放用来插入帖子的网页布局模板。页面布局基于类似博客平台的“一个帖子接一个帖子”的原则，通过YAML前置数据定义。Liquid标签用于在页面上插入帖子的文本内容。

_posts/

该目录下存放的可以说成是你的“动态内容”。这些文件的格式很重要，它们的命名模式必须遵循 YEAR-MONTH-DATE-title.MARKUP 。每一个帖子的固定链接URL可以作弹性的调整，但帖子的发布日期和转换所使用的标记语言会根据且仅根据文件名中的相应部分来识别。

_site/

这里是Jekyll用以存放最终生成站点的根路径位置。也许把它加到你的 .gitignore 列表中会是个不错的主意。

index.html和其他HTML/Markdown/Textile文件

如果一个文件的头部存在YAML前置数据的部分，那么Jekyll将会自动处理转换该文件并传送到站点路径下。这对于站点的根目录或其他任意子目录下的所有 .html 、 .markdown 、 .textile 文件都适用。

其他文件/目录

除了以上提到的文件之外，每一个其他的、不以下划线_开头的目录和文件都会被照原样传送到站点路径下。例如，你可以在网站根目录下面添加一个 css 目录，一个 favicon.ico ，等等等等。假如你对于怎样实现静态站点布局仍然感到困惑的话，那么这里有不少 基于Jekyll的站点 可供参考。

在这些目录下的文件同样会被解析转换和传送，依据处理根目录下文件时的相同规则。

运行Jekyll

通常直接在命令行下使用可执行的Ruby脚本 jekyll ，它可以从gem安装。如果要启动一个临时的Web服务器并测试你的Jekyll站点，执行：

$ jekyll --server

然后在浏览器中访问 http://localhost:4000 或 http://0.0.0.0:4000 。当然这里还有其他许多参数选项可以使用。

在Debian或Ubuntu下，你可能需要将 /var/lib/gems/1.8/bin/ 加到你的PATH环境变量中。

base-url选项

如果你使用了如下的base-url选项

$ jekyll --server --base-url '/blog'

那么确保你所访问的站点地址是

http://localhost:4000/blog/index.html

仅仅访问

http://localhost:4000/blog

是不行的。

部署

由于Jekyll所做的仅仅是生成一个包含HTML等静态网站文件的目录（_site），它可以通过简单的拷贝（scp）、远程同步（rsync）、ftp上传或git等方式部署到任何Web服务器上。

3. 配置

Jekyll允许你以任何可能的方式配置你的站点。以下是目前支持的配置选项的列表。它们均可通过站点根目录下的配置文件 _config.yml 指定。 jekyll 可执行文件同样有一些命令行参数对应于这些配置选项。当配置出现冲突时的优先级顺序是：

  1. 命令行参数
  2. 配置文件中的选项
  3. 默认值

配置选项和命令行参数

设定 配置文件 命令行参数 简述
重新生成 
auto: [boolean]
 --no-auto --auto 允许或禁止Jekyll在文件被修改后重新生成整个站点
本地服务器 
server: [boolean]
 --server 自动开启一个用于托管_site目录的本地Web服务器
本地服务器端口 
server_port: [integer]
 --server [port] 更改Jekyll所使用的服务器端口
Base URL 
baseurl: [BASE_URL]
 --base-url [url] 使用指定的Base URL在服务器上运行站点
站点目的路径 
destination: [dir]
 
jekyll [dest]
 更改Jekyll存放生成文件的路径
站点源路径 
source: [dir]
 
jekyll [source] [dest]
 更改Jekyll所处理文件的路径
Markdown 
markdown: [engine]
 --rdiscount or --kramdown 使用RDiscount或[engine]以取代Maruku
Pygments 
pygments: [boolean]
 --pygments 允许Pygments处理代码语法高亮
LSI 
lsi: [boolean]
 --lsi 产生相关帖子的索引
固定链接 
permalink: [style]
 --permalink=[style] 控制生成帖子的URL
分页 
paginate: [per_page]
 --paginate [per_page] 将你的帖子分成多个子目录："page2"、"page3"、……"pageN"
排除 
exclude: [dir1, file1, dir2]
   不需要进行转换的目录和文件列表
帖子限制 
limit_posts: [max_posts]
 
 --limit_posts=[max_posts]
 限制被转换与发布的帖子数量

注意： 请不要在配置文件中使用Tab制表符。这会导致解析错误，或使Jekyll意外地回退到配置的默认值。

配置的默认值

safe:        false
auto:        false
server:      false
server_port: 4000
baseurl:    /

source:      .
destination: ./_site
plugins:     ./_plugins

future:      true
lsi:         false
pygments:    false
markdown:    maruku
permalink:   date

maruku:
  use_tex:    false
  use_divs:   false
  png_engine: blahtex
  png_dir:    images/latex
  png_url:    /images/latex

rdiscount:
  extensions: []

kramdown:
  auto_ids: true,
  footnote_nr: 1
  entity_output: as_char
  toc_levels: 1..6
  use_coderay: false
  
  coderay:
    coderay_wrap: div
    coderay_line_numbers: inline
    coderay_line_numbers_start: 1
    coderay_tab_width: 4
    coderay_bold_every: 10
    coderay_css: style

补充：Windows平台上的中文支持

在Windows平台上，如果出现类似如下的错误信息：

c:/Ruby192/lib/ruby/gems/1.9.1/gems/jekyll-0.11.0/lib/jekyll/convertible.rb:29:in `read_yaml’: invalid byte sequence in GBK (ArgumentError)

…

你可能需要在命令行下改变当前代码页到UTF-8：

chcp.com 65001

参考链接

了解Jekyll静态网站生成器的起源。Jekyll作者（也是GitHub的共同创始人） Tom Preston-Werner的博文 Blogging like a hacker （中文翻译《 像黑客一样写博客 》 by Kylexlau）。

提供Web托管的 GitHub Pages 和GitHub的项目托管同样使用Git访问。如果你对分布式版本控制系统不熟悉， Pro Git（中文） 是一个极好的起点。

值得推荐的几款文本编辑器（它们都存在对Markdown和Textile的原生或第三方的语法高亮支持）：

你可能会用到的标记语言和模板引擎：

其他关于静态网站生成器的介绍和比较（英文）：

如果想要尝试一些其他的静态网页生成器，这里是一个简略的列表：

  • Ruby
    • Jekyll
    • Bonsai 一个非常简单（但实用）的小脚本
    • Webgen 一个较复杂的生成器
  • Python
    • Hyde Jekyll的Python语言实现版本
    • Cyrax 使用Jinja2模板引擎的生成器
  • PHP
    • Phrozn PHP语言实现的静态网站生成器

更详细的列表和介绍请参见：

posted on 2012-07-02 15:50  zzwworld  阅读(2613)  评论(0)  编辑  收藏  举报

导航