Jekyll 从 0.x 升级到 2.x 注意事项

从旧版本升级到 Jekyll？Jekyll 1.0 和 2.0 中有一些变化需要你特别注意。

在开始之前，先获取最新版本的 Jekyll：

gem update jekyll

快速开始

想快速创建并运行一个新的 Jekyll 网站？只需执行 jekyll new SITENAME，即可创建一个包含基础结构的 Jekyll 网站目录。

Jekyll 命令

为了让命令更加清晰，Jekyll 现在支持 build 和 serve 子命令。

以前你可能只需要运行 jekyll 来生成网站，运行 jekyll --server 来本地预览网站。而从 v2.0（及以后版本）开始，你应该使用 jekyll build 和 jekyll serve 来构建与预览网站。

监听与本地服务

随着新子命令的加入，本地预览网站的方式也发生了一些变化。 以前需要在网站配置文件中设置 server: true，现在直接使用 jekyll serve 即可。 watch: true 也是同样的变化。现在请改用 --watch 参数，并配合 jekyll serve 或 jekyll build 一起使用。

绝对永久链接（Absolute Permalinks）

在 Jekyll v1.0 中，我们为子目录页面引入了绝对永久链接（absolute permalinks）。

从 v2.0 开始，绝对永久链接默认启用，也就是说 Jekyll 默认会使用绝对永久链接，而不是相对永久链接。相对永久链接的兼容支持已在 v3.0 中移除。

从 v3.0 开始将必须使用绝对永久链接

从 Jekyll v3.0 开始，相对永久链接功能将被移除，因此无法继续使用。

草稿文章（Draft Posts）

Jekyll 现在支持草稿文章（Draft Posts），并允许你在正式发布前轻松预览文章效果。

要创建草稿，请在网站源码目录中创建一个 _drafts 文件夹（通常与 _posts 同级），然后在其中添加新的 Markdown 文件。

要预览草稿文章，请运行带有 --drafts 参数的 jekyll serve 命令。

草稿文章没有日期

与正式文章不同，草稿没有发布日期，因为它们尚未发布。 因此，你无需像 2013-07-01-my-draft-post.md 这样命名文件， 只需直接使用未来文章标题作为文件名，例如 my-draft-post.md。

自定义配置文件

现在你可以通过自定义配置文件，而不是单独传递命令行参数，来配置 Jekyll。

这样可以更方便地区分不同环境，或者以编程方式覆盖用户默认配置。

使用方式是在 jekyll 命令后添加 --config 参数，并指定一个或多个配置文件路径（多个文件使用英文逗号分隔，不能有空格）。

已被弃用的命令行参数

因此，以下命令行参数现在已被弃用：

• --no-server
• --no-auto（现改为 --no-watch）
• --auto（现改为 --watch）
• --server
• --url=
• --maruku、--rdiscount 和 --redcarpet
• --pygments
• --permalink=
• --paginate

`config` 参数会明确指定配置文件

如果你使用 --config 参数，Jekyll 将忽略默认的 _config.yml 文件。想把自定义配置与默认配置合并？没问题。 Jekyll 支持通过命令行传入多个配置文件。配置文件会按照从右到左的顺序覆盖。 例如，当执行 jekyll serve --config _config.yml,_config-dev.yml 时， 右侧配置文件（_config-dev.yml）中的相同键值会覆盖左侧配置文件（_config.yml）中的内容。

新的配置文件选项

Jekyll 1.0 引入了多个新的配置文件选项。

升级之前，你应该检查旧版本（pre-1.0）的配置文件中是否包含以下配置项，并确认使用方式是否正确：

• excerpt_separator
• host
• include
• keep_files
• layouts
• show_drafts
• timezone
• url

Baseurl 参数

很多时候，你会希望同一个 Jekyll 网站运行在多个环境中，例如在推送到 GitHub Pages 之前先进行本地预览。

Jekyll 1.0 通过新增 --baseurl 参数，让这件事变得更简单。

要使用该功能，首先在网站的 _config.yml 中设置生产环境使用的 baseurl。

然后，在整个网站中，给相对链接添加 {{ site.baseurl }} 前缀。

当你准备本地预览网站时，只需在执行 jekyll serve 时通过 --baseurl 参数传入本地 baseurl（通常是 /），Jekyll 就会自动替换对应值，从而确保链接在不同环境下都能正常工作。

所有页面和文章 URL 都带有前导斜杠

如果你使用上述方法，请记住： 所有文章和页面的 URL 都包含前导斜杠。 因此，当 site.baseurl = / 且 post.url = /2013/06/05/my-fun-post/ 时，直接拼接两者会得到两个连续斜杠，从而导致链接失效。 因此，建议仅在 baseurl 不是默认值 / 时，才使用 site.baseurl 作为前缀。