从 0.x 升级到 2.x 版本

优质

小牛编辑

130浏览

2023-12-01

如果您打算升级一个早先版本的 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 命令来创建并预览您的站点。

运行并浏览

由于全新的命令行，您在本地预览站点的方式将发生些小小的变化。目前站点配置文件中已使用 jekyll serve 来取代早先的server: true。类似的也针对于 watch: true。取而代之地，请结合 jekyll serve 或 jekyll build 使用 --watch 标识。

绝对永久链接

在 Jekyll v1.0 中，我们对于子目录下的页面推出了绝对永久链接。而从 v2.0 开始，绝对永久链接的选项将会不再可用。这便意味着 Jekyll 将默认使用绝对永久链接来取代相对永久链接。相对永久链接的向后兼容性也会在 v3.0 中被移除。

在 v3.0 中将使用绝对永久链接

从 Jekyll v3.0 起，相对永久链接的功能将会被移除。因此它将不再可用。

草稿文章

Jekyll 现在支持使用草稿。且能让您更佳方便地在发布前预览它们。若需要使用草稿，只需要在您的站点资源目录下建立一个名为 _drafts 的文件夹（例如就在 _posts 文件夹旁），同时加入一个新的 markdown 文件。若想预览您的草稿文章，只要执行 jekyll serve 并带上 --drafts 即可。

草稿不具备日期

不像一般您撰写的文章，草稿并不具备日期，这是因为它们仍未被发布。因此，与其将您的草稿命名为 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 标识，Jekyll 将会忽略您的 _config.yml 文件。那么您是否希望自定义的配置文件能与常规的配置文件一起使用呢？没问题！通过命令行，Jekyll 能同时支持多个配置文件。配置文件将以从右到左的瀑布流分布，例如执行 jekyll serve --config _config.yml,_config-dev.yml，那么位居右侧的配置文件的变量（_config-dev.yml）将会覆盖左侧（_config.yml）文件中两者同时包含的配置选项.

全新的配置文件选项

在 1.0 版本中，Jekyll 推出了几个全新的配置文件选项。在您升级之前，您应该仔细检查您的配置文件是否存在以下配置选项。若存在，请确保它们能正常使用：

excerpt_separator
host
include
keep_files
layouts
show_drafts
timezone
url

Baseurl

通常你会喜欢在多个场景中共同管理同一个 Jekyll 站点。例如您会在将文章发布到 Github Pages 之前，先在本地进行预览。 Jekyll 1.0 通过 --baseurl 标识让这一切变得更加简单。若想利用这一特性，只需先将 baseurl 添加到您站点的 _config.yml 文件中。然后在全站范围内，通过 {{ site.baseurl }} 简单修正下您的相对 URL 即可。当您准备在本地预览您的站点时，请使用 jekyll serve 并带上 --baseurl 和您的本地 baseurl （一般是 /）。Jekyll 将会修改您的链接，并确保您的所有链接在不同环境中都正常工作。

所有页面和文章的 URL 都将包含有前置斜杠

如果您使用上述的方法进行操作，那请注意所有页面及文章的 URL 都将包含有前置斜杠。如此一来，所有链接到站点的 baseurl 如 site.baseurl = /，以及文章或页面的 url 如 post.url = /2013/06/05/my-fun-post/，就将产生两个前置斜杠。这将会导致链接失效！因此建议，只有当 baseurl 不是默认的 / 时，才对 site.baseurl 进行修改。