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

如果您打算升级一个早先版本的 Jekyll,那么一些发生在 1.0 及 2.0 版本中的相关变化,您需要首先了解下。

在我们开始动手之前,请先获取最新版本的 Jekyll:

$ gem update jekyll
立即开始

想快速构建并运行一个全新的 Jekyll 站点吗?那么只要执行 jekyll new SITENAME 即可!该命令会创建一个包含了 Jekyll 最基础框架的文件夹。

Jekyll 命令行

为提升可读性,Jekyll 现已支持 buildserve 命令。在此之前,您可能通过执行 jekyll 来生成一个站点,并使用 jekyll --server 进行本地预览。在 v2.0(及之后的版本)中请您使用 jekyll buildjekyll serve 命令来创建并预览您的站点。

运行并浏览

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

绝对永久链接

在 Jekyll v1.0 中,我们对于子目录下的页面推出了绝对永久链接。而从 v2.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 进行修改。

此网站由 @xcatliu 维护,由 开源爱好者们 共同翻译。若发现错误或想贡献翻译,请访问: xcatliu/jekyllCN