Jekyll使用教程笔记 一

---

目录

• 《Jekyll使用教程笔记 一：简介、快速开始、基本用法、目录结构》
• 《Jekyll使用教程笔记 二：配置》
• 《Jekyll使用教程笔记 三：Front Matter、写文章》
• 《Jekyll使用教程笔记 四：建立页面、静态文件、变量》
• 《Jekyll使用教程笔记 五：合集、数据文件》
• 《Jekyll使用教程笔记 六：资源、博客迁移、模版》

---

简介

Jekyll是一个简单的，博客感知的静态站点生成器。

你将内容建立为文本文件（Markdown），并将其放到到文件夹中。而后，使用Liquid-enhanced HTML模板构建网站。Jekyll自动将内容和模板联系在一块儿，生成彻底由静态资源组成的网站，它适合上传到任何服务器。

Jekyll刚好是GitHub Pages的引擎，所以你能够在GitHub的服务器上免费托管项目的Jekyll页面/博客/网站。

快速开始

若是你已经安装了包含全部头文件和RubyGems的完整的Ruby开发环境（请参阅Jekyll的要求），你能够经过执行如下操做来建立一个新的Jekyll站点：

# 经过RubyGems安装Jekyll和Bundler gems
gem install jekyll bundler
# 若是没法安装请尝试：sudo gem install jekyll bundler
# 上面两个命令都没法安装，请尝试：sudo gem install -n /usr/local/bin jekyll bundler
# 若是仍没法解决，请尝试关闭SIP

# 在./myblog建立一个新的Jekyll站点
jekyll new myblog

# 进入到生成的文件夹中
cd myblog

# 在本地预览服务中编译站点
bundle exec jekyll serve

# 浏览器里面打开 http://localhost:4000
复制代码

若是你在上述过程当中遇到任何意外错误，好比可能缺乏开发头文件或其余先决条件，请参阅故障排除页面或前面提到的需求页面。

关于Bundler

gem install bundler命令将经过RubyGems安装bundler gem。你只须要安装一次便可——不用每次建立一个Jekyll项目的时候都安装一次。这里有一些额外的细节：

• bundler是一个管理其余Ruby gems的gem。它确保你的gems和gem版本兼容，而且确保包含每一个gem须要的必须依赖。

• Gemfile和Gemfile.lock文件将告知Bundler有关于你的站点中的gem依赖。若是你的站点没有这些Gemfile文件，则能够省略bundle exec命令，直接运行jekyll serve命令。

• 当你运行bundle exec jekyll serve时，Bundler使用Gemfile.lock中指定的gem和版原本确保你的Jekyll站点没有兼容性或依赖冲突。

有关如何在Jekyll项目中使用Bundler的更多信息，这个教程能够为最多见的问题提供答案，并解释如何快速启动和运行。

使用Jekyll建立一个新的站点的选项

jekyll new <PATH>在指定的路径（相对于当前目录）安装一个新的Jekyll站点。 在上面列出的命令行的状况下，Jekyll将被安装在当前目录下的名为myblog的目录中。这里有一些额外的细节：

• 要将Jekyll站点安装到你当前所在的目录中，请运行jekyll new .。 若是现有的目录不是空的，你可使用jekyll new . --force传递--force选项。

• jekyll new会自动启动bundle install以安装所需的依赖关系。 （若是你不想让Bundler安装gem，请使用jekyll new myblog --skip-bundle。）

• 默认状况下，由jekyll new安装的Jekyll站点使用一个叫作为Minima的基于gem的主题。使用基于gem的主题，一些目录和文件存储在gem主题中，隐藏在你的即时视图中。

• 咱们建议你将Jekyll设置为基于gem的主题，但若是你想从空白的模版开始，请使用jekyll new myblog --blank。

• 要了解其余参数，你可使用jekyll new，输入jekyll new --help便可。

若是有疑问，请使用help命令来提示你全部可用的选项和用法，它也适用于new和build以及serve命令，例如，jekyll help new或jekyll help build。

基本用法

Jekyll gem在终端窗口中为你提供了一个jekyll可执行文件。你能够经过多种方式使用此命令：

jekyll build
# => 当前文件夹中的内容将被生成到./_site

jekyll build --destination <destination>
# => 当前文件夹中的内容将被生成到<destination>

jekyll build --source <source> --destination <destination>
# => <source>文件夹中的内容将被生成到<destination>

jekyll build --watch
# => 当前文件夹中的内容将被生成到./_site,
# 检查改动，并自动从新生成。
复制代码

重写默认开发配置

开发环境的默认预览地址是http://localhost:4000。[3.3.0]

若是你想为你的生产环境构建：

• 在_config.yml中设置你的生产环境URL。例如：https://example.com。
• 运行JEKYLL_ENV=production bundle exec jekyll build。

注意: _config.yml的更改并不会在自动生成更新过程当中生效。

_config.yml主要配置文件会在执行时读取一次全局配置和变量定义。在下次执行以前，不会加载在自动生成更新期间对_config.yml所作的更改。

注意，自动生成更新过程当中会对Data Files从新加载。

警告：目标文件夹在网站构建的时候会被清空

默认状况下，当网站构建的时候，<destination>中的内容会被自动的清空。不是被你的网站构建时所建立的文件和文件夹都会被删除。能够在<keep_files>配置指令中指定你但愿保留在中的文件和文件夹。

不要设置为重要本地路径；相反，应该将其用做暂存区域并将文件从那里复制到你的Web服务器。

Jekyll还附带了一个内置的开发服务器，可让你在本地浏览中浏览生成的网站。

jekyll serve
# => 开发服务将会运行在http://localhost:4000/
# 自动生成更新会被开启，若是不想开启请使用`--no-watch`。

jekyll serve --no-watch
# => 等同于`jekyll serve`，可是内容更改时不会自动生成新的。

jekyll serve --livereload
# LiveReload将在更新后刷新浏览器页面。

jekyll serve --incremental
# Incremental将会匹配更改部分，执行部分构建以减小自动生成更新时间。

jekyll serve --detach
# => 等同于`jekyll serve`，可是不会再当前终端中显示运行状态，而是转为后台模式。
# 若是你须要关闭服务，你能够`kill -9 1234`，这里的"1234"是PID。
# 若是你不知道PID，那么就执行`ps aux | grep jekyll`并关闭这个实例。
复制代码

这些只是几个可用的配置选项。许多配置选项能够在命令行中指定为flags，或者（更常见）它们能够在源目录的根目录下的_config.yml文件中指定。运行时，Jekyll会自动使用该文件中的选项。例如，若是将如下行放在_config.yml文件中：

source:      _source
destination: _deploy
复制代码

那么如下两个命令将是等效的：

jekyll build
# 上面的命令添加过配置后等于下面的命令没加配置
jekyll build --source _source --destination _deploy
复制代码

有关配置选项的更多信息，请参阅配置页面。

注意：寻求帮助

help命令老是在这里提示你全部可用的选项和用法，它也适用于new和build以及serve命令，例如，jekyll help new或jekyll help build。

若是你有兴趣想要随时浏览这些文档，请安装jekyll-docsgem，并在你的终端中运行jekyll docs。

目录结构

Jekyll的核心是一个文本转换引擎。这个系统的大概是：你给它的内容能够用你最喜欢的标记语言编写，能够是Markdown，是Textile或者是纯粹的HTML，而后Jekyll经过一个或一系列布局文件混合它们。在整个过程当中，你能够调整网站URL的样式，布局中显示的数据等等。这一切都是经过编辑文本文件完成的，而静态网站就是它的最终产品。

基本的Jekyll站点一般看起来像这样：

.
├── _config.yml
├── _data
|   └── members.yml
├── _drafts
|   ├── begin-with-the-crazy-ideas.md
|   └── on-simplicity-in-technology.md
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2007-10-29-why-every-programmer-should-play-nethack.md
|   └── 2009-04-26-barcamp-boston-4-roundup.md
├── _sass
|   ├── _base.scss
|   └── _layout.scss
├── _site
├── .jekyll-metadata
└── index.html # can also be an 'index.md' with valid YAML Frontmatter
复制代码

注意：使用基于gem的主题的Jekyll网站的目录结构

始于Jekyll 3.2，一个使用jekyll new建立的基于gem的主题来定义网站外观的新的Jekyll项目，会有一个比较简单的默认目录结构：默认状况下，_layouts，_includes和_sass会被存储在theme-gem中，而不是放在项目目录中。

minima是当前的默认主题，bundle show minima会告诉你minima主题的文件存储在计算机上的哪一个位置。

目录结构说明：

文件/文件夹	说明
_config.yml	存储配置数据。这些配置中的许多选项均可以从命令行中指定，但在这里指定它们更加容易，而且你没必要记住它们。
_drafts	草稿是未发布的文章。这些文件的命名格式是没有日期的：title.MARKUP。了解如何使用草稿。
_includes	These are the partials that can be mixed and matched by your layouts and posts to facilitate reuse. The liquid tag {% include file.ext %} can be used to include the partial in _includes/file.ext.
_layouts	这些是包装文章的模板。在YAML Front Matter中逐层选择布局，这将在下一节中介绍。 The liquid tag {{ content }}用于将内容注入网页。
_posts	能够这么说，这里是你的动态内容。这些文件的命名约定很重要，而且必须遵循如下格式：YEAR-MONTH-DAY-title.MARKUP。能够为每篇文章指定固定连接，但日期和MARKUP语言彻底由文件名决定。
_data	格式良好的网站数据应该放在这里。Jekyll引擎将自动加载该目录中的全部数据文件（使用.yml，.yaml，.json或.csv格式和扩展名），而且能够经过site.data访问它们。若是目录下有文件members.yml，则能够经过site.data.members访问该文件的内容。
_sass	些是能够导入到main.scss中的sass部分，而后将它们处理成一个样式表main.css，该样式表定义了你的网站使用的样式。
_site	这是Jekyll完成转换后，生成的网站将被存放的（默认）位置。建议将它添加到.gitignore文件中。
.jekyll-metadata	临时文件，这些将帮助Jekyll追踪自上次构建站点后哪些文件未被修改，以及哪些文件须要在下一个版本中从新生成。该文件不会包含在生成的网站中。建议将它添加到.gitignore文件中。
index.html或index.md或其余HTML、Markdown文件	假设该文件具备YAML Front Matter部分，它将由Jekyll进行转换。网站根目录中的任何.html，.markdown，.md或.textile文件或上面未列出的目录也会发生一样的状况。
其余文件/文件夹	除了上面列出以外的其余文件夹和文件（例如css和images文件夹，favicon.ico文件等），将会被逐字复制到生成的网站中。若是你想知道它们是如何布置的，有不少网站已经在使用Jekyll。