Question

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

配置设置

全局配置

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

设置	选项 和 标记
Site Source 修改 Jekyll 读取文件的路径	source: DIR -s, --source DIR
Site Destination 修改 Jekyll 写入文件的路径	destination: DIR -d, --destination DIR
Safe 禁用 自定义插件。	safe: BOOL --safe
Exclude 转换时排除某些文件、文件夹	exclude: [DIR, FILE, ...]
Include 转换时强制包含某些文件、文件夹。.htaccess 是个典型的例子，因为默认排除 . 开头的文件。	include: [DIR, FILE, ...]
Keep files 当生成站点时，保留选择的文件。对文件不是由 jekyll 生成是有用的。例如由你的构建工具生成的文件或者资源。路径是相对于 destination 。	keep_files: [DIR, FILE, ...]
Time Zone 设置时区，这个设置作用于 TZ 变量， Ruby 用它来处理日期和时间。 IANA Time Zone Database 里边的都有效，比如 America/New_York 。默认值为操作系统的时区。	timezone: TIMEZONE
Encoding 设置文件的编码，仅 Ruby 1.9 以上可用。2.0.0　版本以后默认值为 utf-8，之前版本默认值为 nil，使用 Ruby 默认的 ASCII-8BIT。可以用命令 ruby -e 'puts Encoding::list.join("\n")' 查看 Ruby 可用的编码。	encoding: ENCODING
Defaults 设置 YAML 头信息 的默认值。	详细

Destination 文件夹会在站点建立时被清理

<destination> 的内容默认在站点建立时会被自动清理。不是你创建的文件和文件夹会被删除。你想在 <destination> 保留的文件和文件夹应在 <keep_files> 里指定。

不要把<destination> 设置到重要的路径上，而应该把它作为一个暂存区域,从那里复制文件到您的web服务器。

编译选项

设置	选项 和 标记
Regeneration 允许文件修改时自动重新生成网站。	-w, --watch
Configuration 手动设置配置文件，可设置多个，且后边的配置会覆盖前边的。	--config FILE1[,FILE2,...]
Drafts 处理草稿	--drafts
Environment build　时使用特定的环境变量。	JEKYLL_ENV=production
Future 用将来的日期发布文章	future: BOOL --future
LSI 为相关文章生成索引	lsi: BOOL --lsi
Limit Posts 限制文章的数量	limit_posts: NUM --limit_posts NUM
Force polling 强制使用轮询。	--force_polling
Verbose output 显示详细输出。	-V, --verbose
Silence Output 在编译期间不显示的正常输出。	-q, --quiet
Incremental build 启用实验特性 incremental build。Incremental build 只重建修改过的 posts 和 pages，对大型网站有显著的性能提升，但在特定情况下也会影响网站生成。	incremental: BOOL -I, --incremental
Liquid profiler 生成一个Liquid概述文档来帮助你发现性能瓶颈	profile: BOOL --profile

服务选项

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

设置	选项 和 标记
Local Server Port 监听所给的端口	port: PORT --port PORT
Local Server Hostname 监听所给的主机名	host: HOSTNAME --host HOSTNAME
Base URL 网站的根路径	baseurl: URL --baseurl URL
Detach 从终端命令行中分离出来	detach: BOOL -B, --detach
Skips the initial site build. 跳过服务器启动之前，网站的初始化。	--skip-initial-build
X.509 (SSL) Private Key SSL私钥	--ssl-key
X.509 (SSL) Certificate SSL公证	--ssl-cert

不要在配置文件中使用 tab 制表符

这将造成解析错误，或倒回到默认设置。请使用空格替代。

自定义 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"

请重新运行命令： `jekyll serve`

主要配置文件 _config.yml 包括一些在运行时一次性读入的全局配置和变量定义， 在自动生成的过程中并不会重新加载 _config.yml 文件所发生的改变，除非重新运行。

注意 Data Files 包括在自动生成范围内，可以在更改后自动重新加载。

在这里，我们把 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 默认使用以下的配置运行。也可以在配置文件或者命令行中显示地指定这些选项。

有两个 kramdown 的选项不支持

注意 Jekyll 当前不支持 remove_block_html_tags 和 remove_span_html_tags ，因为没有被包含到 kramdown HTML 转换器中。

# 目录结构
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 依旧是一个实验特性

incremental regeneration 在大多数情况下可以工作，但不可能在所有情况下都能够正常工作。请一定小心使用该特性，报告任何未列出在下边的问题。opening an issue on GitHub.

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 启用。