配置

Jekyll允许你很轻松的设计你的网站，这很大程度上归功于灵活强大的配置功能。既可以配置在网站根目录下的 _config.yml 文件，也可以作为命令行的标记来配置。

配置设置

全局配置

下表中列举了所有 Jekyll 可用的设置，和多种多样的 选项 (配置文件中) 及 标记 (命令行中)。

编译选项

服务选项

除了下边的选项， serve 命令还可以接收 build 的选项，当运行网站服务之前的编译时候使用。

自定义 WEBRick 标题

你可以在 _config.yml 中为你的站点提供自定义标题

# 文件: _config.yml
webrick:
  headers:
    My-Header: My-Value
    My-Other-Header: My-Other-Value

默认

我们只提供一个默认，而且这是一个不能在开发模式里缓存的 content-type 头，所以当你处于开发模式时，不用理会 chrome 的 aggressive　caching。

指定 Jekyll build 时的环境

在 build（或者 serve）参数中，你能指定 Jekyll 的环境和参数。然后 build 会将参数应用在你内容中任意的条件语言。

例如，在你代码中的条件语句中应用你的设置：

{% if jekyll.environment == "production" %}
   {% include disqus.html %}
{% endif %}

当你 build 你的 Jekyll 网站时，if 语句块中的内容不会被执行；除非你在 build 命令中还指定了一个 production 环境，像这样：

JEKYLL_ENV=production jekyll build

设置环境变量允许你只在特定环境下执行指定内容。

JEKYLL_ENV 的默认值是 development。因此，如果你在 build 参数中省略 JEKYLL_ENV，那么默认为 JEKYLL_ENV=development。任何 {% if jekyll.environment == "development" %} 中的内容在 build 时都会自动显现。

你的环境参数可以任意设置（不止是 development 或者 production ）。你可能想在开发环境下一些隐藏的元素，比如评论功能、谷歌分析。你可能想在 development environment 开发环境扩展一个“在 GitHub 中编辑”的按钮，而不包括在 production environments 中。

在 build 命令中指定参数，当你迁移环境时，可以避免更改你配置文件中的值。

头信息默认值

通过使用 YAML 头信息可以指定站点的页面和文章的配置。设置一些东西例如布局或者自定义标题，亦或是给文章指定一个更精确的日期/时间，这都可以往页面或文章的头信息添加数据来实现。

很多时候，你会发现你在重复填写很多配置项。在每个文件里设置相同的布局，对每篇文章添加相同的分类，等等。你甚至可能添加自定义变量，如作者名，这可能对你博客上大部分的文章来说是相同的。

Jekyll 提供了一个方法在站点配置中设置这些默认值，而不是在每次创建一个新的文章或页面重复此配置。要做到这一点，你可以在项目根目录下的 _config.yml 文件里设置 defaults 的值指定全站范围的默认值。

defaults 保存一个范围/值的对的数组，这定义了哪些默认值要设置到一个特定的文件路径下的文件，或者可选的，在该路径下指定 的文件类型的文件。

假设您想添加一个默认的布局给站点中的所有页面和文章。 你要将这添加到你的 _config.yml 文件：

defaults:
  -
    scope:
      path: "" # 一个空的字符串代表项目中所有的文件
    values:
      layout: "default"

在这里，我们把 values 应用给 scope 路径里的所有文件。因为路径被设为空字符串，它将会应用到你项目里的全部文件。你可能不想给项目在的每个文件都设置一个布局，例如 css 文件，所以你可以在 scope 下指定 type 的值。

defaults:
  -
    scope:
      path: "" # 一个空的字符串代表项目中所有的文件
      type: "posts" # 以前的 `post`， 在 Jekyll 2.2 里。
    values:
      layout: "default"

现在，这只会给类型是 posts 的文件设置默认布局。你可以使用的不同的类型分别是 pages ， posts ， drafts 或者其他你站点中的集合。当创建一个范围/值的对，如果选择了 type，你必须指定一个值给 path 。

正如前面所提到的，您可以给 defaults 设置多个范围/值的对。

defaults:
  -
    scope:
      path: ""
      type: "posts"
    values:
      layout: "my-site"
  -
    scope:
      path: "projects"
      type: "pages" # 以前的 `page`， 在 Jekyll 2.2 里。
    values:
      layout: "project" # 覆盖之前的默认布局
      author: "Mr. Hyde"

有了这些默认值，所有的文章都会使用 my-site 布局。任何在 projects/ 文件夹下的 html 文件会使用 project 布局。这些文件也会拥有值为 Mr. Hyde 的 page.author 这一 liquid 变量，同时这些页面的类别被设为 project 。

collections:
  - my_collection:
    output: true

defaults:
  -
    scope:
      path: ""
      type: "my_collection" # 你的站点里的一个集合，复数形式
    values:
      layout: "default"

在这个例子中，在 collection 里面 layout 被设为 default ，用 my_collection 的名字。

优先权

Jekyll 会应用你在 _config.yml 文件里 defaults 部分的所有配置设定。然而，你可以选择 覆盖这些设定，通过在范围/值的对里指定一个更具体的路径。

你可以观察上一个例子。一开始我们设置了 my-site 这一默认的布局。然后，使用一个更具体的路径， 我们把在 projects/ 路径下的文件的默认布局设置为 project 。这可以使用你想在页面或者文章的头信息里设定的任意值来达成。

最后，如果你在 _config.yml 的 defaults 部分设置了站点的默认值，你可以在页面或文章的文件里覆盖这些设定。你需要做的是在在页面或文章的头信息里指定要覆盖的设定。例如：

# In _config.yml
...
defaults:
  -
    scope:
      path: "projects"
      type: "pages"
    values:
      layout: "project"
      author: "Mr. Hyde"
      category: "project"
...

# In projects/foo_project.md
---
author: "John Smith"
layout: "foobar"
---
The post text goes here...

在站点建立时 projects/foo_project.md 的布局会是 foobar而不是project ， author 是 John Smith而不是 Mr. Hyde 。

默认配置

Jekyll 默认使用以下的配置运行。也可以在配置文件或者命令行中显示地指定这些选项。

# 目录结构
source:      .
destination: ./_site
plugins:     ./_plugins
layouts:     ./_layouts
data_source: ./_data
collections: null

# 阅读处理
safe:         false
include:      [".htaccess"]
exclude:      []
keep_files:   [".git", ".svn"]
encoding:     "utf-8"
markdown_ext: "markdown,mkdown,mkdn,mkd,md"

# 内容过滤
show_drafts: null
limit_posts: 0
future:      true
unpublished: false

# 插件
whitelist: []
gems:      []

# 转换
markdown:    kramdown
highlighter: rouge
lsi:         false
excerpt_separator: "\n\n"
incremental: false

# 服务器选项
detach:  false
port:    4000
host:    127.0.0.1
baseurl: "" # does not include hostname

# 输出
permalink:     date
paginate_path: /page:num
timezone:      null

quiet:    false
defaults: []

# Markdown 处理器
rdiscount:
  extensions: []

redcarpet:
  extensions: []

kramdown:
  auto_ids:       true
  footnote_nr:    1
  entity_output:  as_char
  toc_levels:     1..6
  smart_quotes:   lsquo,rsquo,ldquo,rdquo
  enable_coderay: false

  coderay:
    coderay_wrap:    div
    coderay_line_numbers:      inline
    coderay_line_number_start: 1
    coderay_tab_width:         4
    coderay_bold_every:        10
    coderay_css:     style

Liquid 选项

Liquid的错误处理方式可以通过 error_mode 来配置，可选项有：

• lax — 忽略所有错误
• warn — 针对每个错误在控制台中输出警告信息
• strict — 输出错误信息并停止构建过程

Markdown 选项

Jekyll 支持的 Markdown 渲染器中有的有额外的选项。

Redcarpet

Redcarpet支持设置 extensions ，值为一个字符串数组，每个字符串都是 Redcarpet::Markdown 类的扩展，相应的扩展就会设置为 true 。

Jekyll 处理两个特别的 Redcarpet 扩展：

• no_fenced_code_blocks — 默认的， Jekyll 设置扩展 fenced_code_blocks (用三个波浪线或重音线标记代码区间) 为 true ，这或许是跟 GitHub 积极的采用有关。当使用Jekyll的时候， Redcarpet 的扩展 fenced_code_blocks 无效，作为替代方案，你可以使用这个语义相反的扩展来禁用 fenced code 。

注意你还可以这样来配置语言以支持语法高亮：

    ```ruby
    # ...ruby code
    ```

有了 fenced code blocks 和 highlighter enabled，就会静态地高亮代码了；如果没有任何高亮语法 syntax hightlighter，将增加一个 class="LANGUAGE" 属性到 <code> 元素，用于给不同的 JavaScript 代码高亮库做为提示。

• smart — 这个伪扩展pseudo-extension会打开 SmartyPants ，将引号转为 " 、连字符转为 em (---) 和 en (--) 破折号。

Redcarpet 所有其他扩展保持他们本来的名字，并且在 Jekyll 中不能给 smart 加渲染选项。 Redcarpet 的 README 中有可用扩展的列表。 确保你看的 README 是正确的版本：Jekyll 当前用的是 v3.2.x。最常用的扩展是如下：

• tables
• no_intra_emphasis
• autolink

Kramdown

除了上面提到的默认值，你可以打开 Github Flavored Markdown 的识别，通过输入一个 值为 “GFM” 的 input 选项。

例如，在你的 _config.yml 中：

kramdown:
  input: GFM

自定义 Markdown 处理器

如果你对创建一个自定义 Markdown 处理器感兴趣，你真的很幸运！在 Jekyll::Converters::Markdown 的命名空间下新建一个类：

class Jekyll::Converters::Markdown::MyCustomProcessor
  def initialize(config)
    require 'funky_markdown'    @config = config
  rescue LoadError
    STDERR.puts 'You are missing a library required for Markdown. Please run:'    STDERR.puts '  $ [sudo] gem install funky_markdown'    raise FatalException.new("Missing dependency: funky_markdown")
  end

  def convert(content)
    ::FunkyMarkdown.new(content).convert
  end
end

一旦你建立了你的类，并且它作为一个插件被正确安装到 _plugins 文件夹 或者 作为 gem 被正确安装，你要在你的 _config.yml 里指定它：

markdown: MyCustomProcessor

Incremental Regeneration

Incremental regeneration 只加载更新过的文件和页面来帮助缩短 build 时间。这是通过对文件修改次数和 .jekyll-metadata 文件中的依赖关系的追踪实现的。

在目前的实现中，incremental regeneration 会更新一个文件或者页面，仅当它或它其中之一的依赖被修改时。现今，被追踪的依赖类型仅有 includes（{% include %} 标签）和 layouts。这意味着对其它文件的 plain　references（例如，在博客列表页面中常见的 site.posts 递归）不会被检测为依赖。

为了补救其中一些缺陷，在文件的头信息中添加 regenerate: true 会强迫 Jekyll 重建文件，不管文件是否被修改。注意这样做仅重建指定文件；指向其它文件内容的 references 不会起作用，因为它们不会被再次执行。

Incremental regeneration 可以在命令行中经由 --incremental flag（简写为 -I）启用，或者在配置文件中写入 incremental: true 启用。