Jekyll中文文档__Configuration

Jekyll为您提供了很大的灵活性来定制它如何构建您的网站。这些选项可以在站点根目录中的 _config.yml 或 _config.toml 文件中指定，也可以指定为终端中 jekyll 可执行文件的 flags 。

配置选项

下表列出了Jekyll 的可用设置，以及控制它们的各种 options（在配置文件中指定）和 flags （在命令行上指定）。

全局配置

Setting	Options and Flags
Site source Change the directory where Jekyll will read files	source: DIR -s, --source DIR
Site destination Change the directory where Jekyll will write files	destination: DIR -d, --destination DIR
Safe Disable non-whitelisted plugins, caching to disk, and ignore symbolic links.	safe: BOOL --safe
Disable disk cache 4.1.0 Disable caching of content to disk in order to skip creating a .jekyll-cache or similar directory at the source to avoid interference with virtual environments and third-party directory watchers. Caching to disk is always disabled in safe mode.	disable_disk_cache: BOOL --disable-disk-cache
Ignore theme configuration 4.1.0 Jekyll 4.0 started allowing themes to bundle a _config.yml to simplify theme-onboarding for new users. In the unfortunate situation that importing a bundled theme configuration messes up the merged site-configuration, the user can configure Jekyll to not import the theme-config entirely.	ignore_theme_config: BOOL
Exclude Exclude directories and/or files from the conversion. These exclusions are relative to the site's source directory and cannot be outside the source directory.	exclude: [DIR, FILE, ...]
Include Force inclusion of directories and/or files in the conversion. .htaccess is a good example since dotfiles are excluded by default.	include: [DIR, FILE, ...]
Keep files When clobbering the site destination, keep the selected files. Useful for files that are not generated by jekyll; e.g. files or assets that are generated by your build tool. The paths are relative to the destination.	keep_files: [DIR, FILE, ...]
Time zone Set the time zone for site generation. This sets the TZ environment variable, which Ruby uses to handle time and date creation and manipulation. Any entry from the IANA Time Zone Database is valid, e.g. America/New_York. A list of all available values can be found here. When serving on a local machine, the default time zone is set by your operating system. But when served on a remote host/server, the default time zone depends on the server's setting or location.	timezone: TIMEZONE
Encoding Set the encoding of files by name (only available for Ruby 1.9 or later). The default value is utf-8 starting in 2.0.0, and nil before 2.0.0, which will yield the Ruby default of ASCII-8BIT. Available encodings can be shown by the command ruby -e 'puts Encoding::list.join("\n")'.	encoding: ENCODING
Defaults Set defaults for front matter variables.	see below
========================================================	=======================================

在站点生成中清除目标文件夹

默认情况下，当站点建立时，＜destination＞ 的内容会自动清除。非您的网站创建的文件或文件夹将被删除。通过在＜keep_files＞配置指令中指定某些文件，可以保留这些文件。

不要将＜destination＞用于重要的位置；相反，将其用作临时区域，并将文件从那里复制到您的web服务器。

Build 命令选项

Setting	Options and Flags
Regeneration Enable auto-regeneration of the site when files are modified.	-w, --[no-]watch
Configuration Specify config files instead of using _config.yml automatically. Settings in later files override settings in earlier files.	--config FILE1[,FILE2,...]
Plugins Specify plugin directories instead of using _plugins/ automatically.	plugins_dir: [ DIR1,... ] -p, --plugins DIR1[,DIR2,...]
Layouts Specify layout directory instead of using _layouts/ automatically.	layouts_dir: DIR --layouts DIR
Drafts Process and render draft posts.	show_drafts: BOOL -D, --drafts
Environment Use a specific environment value in the build.	JEKYLL_ENV=production
Future Publish posts or collection documents with a future date.	future: BOOL --future
Unpublished Render posts that were marked as unpublished.	unpublished: BOOL --unpublished
LSI Produce an index for related posts. Requires the classifier-reborn plugin.	lsi: BOOL --lsi
Limit posts Limit the number of posts to parse and publish.	limit_posts: NUM --limit_posts NUM
Force polling Force watch to use polling.	force_polling: BOOL --force_polling
Verbose output Print verbose output.	verbose: BOOL -V, --verbose
Silence output Silence the normal output from Jekyll during a build.	quiet: BOOL -q, --quiet
Log level Specify a log level among debug, info, warn, or error.	JEKYLL_LOG_LEVEL=info
Incremental build Enable the experimental incremental build feature. Incremental build only re-builds posts and pages that have changed, resulting in significant performance improvements for large sites, but may also break site generation in certain cases.	incremental: BOOL -I, --incremental
Disable bundle require Disables the need to require gems in `:jekyll_plugins` Gemfile	JEKYLL_NO_BUNDLER_REQUIRE=true
Liquid profiler Generate a Liquid rendering profile to help you identify performance bottlenecks.	profile: BOOL --profile
Strict front matter Cause a build to fail if there is a YAML syntax error in a page's front matter.	strict_front_matter: BOOL --strict_front_matter
Base URL Serve the website from the given base URL.	baseurl: URL -b, --baseurl URL
Trace Show the full backtrace when an error occurs.	-t, --trace
===============================================

Serve 命令行选项

除了以下选项外，serve 子命令还可以接受 build 子命令的任何选项，然后将这些选项应用于站点构建，该站点构建发生在您的站点得到运行之前。

Setting	Options and Flags
Local server port Listen on the given port. The default is `4000`.	port: PORT -P, --port PORT
Local server hostname Listen at the given hostname. The default is `localhost`.	host: HOSTNAME -H, --host HOSTNAME
Live reload Reload a page automatically on the browser when its content is edited.	livereload: BOOL -l, --livereload
Live reload ignore File glob patterns for LiveReload to ignore.	livereload_ignore: [ GLOB1,... ] --livereload-ignore GLOB1[,GLOB2,...]
Live reload min/max delay Minimum/Maximum delay before automatically reloading page.	livereload_min_delay: SECONDS livereload_max_delay: SECONDS --livereload-min-delay SECONDS --livereload-max-delay SECONDS
Live reload port Port for LiveReload to listen on.	--livereload-port PORT
Open URL Open the site's URL in the browser.	open_url: BOOL -o, --open-url
Detach Detach the server from the terminal.	detach: BOOL -B, --detach
Skips the initial site build Skips the initial site build which occurs before the server is started.	skip_initial_build: BOOL --skip-initial-build
Show directory listing Show a directory listing instead of loading your index file.	show_dir_listing: BOOL --show-dir-listing
X.509 (SSL) private key SSL Private Key, stored or symlinked in the site source.	--ssl-key
X.509 (SSL) certificate SSL Public certificate, stored or symlinked in the site source.	--ssl-cert
===============================================	================================================

不要在配置文件中使用 tabs

这将导致解析错误，或者Jekyll将恢复到默认设置。请改用空格。

默认配置

默认情况下，Jekyll使用以下配置选项运行。可以在配置文件或命令行中明确指定这些选项的替代设置。

注意目录路径

通常，使配置里"键"（如 plugins_dir ）中的目录路径"值"相对于当前工作目录，而不是站点 source 。sass 配置"键"是一个例外，其"值"必须相对于站点 source 。

# Where things are
source              : .
destination         : ./_site
collections_dir     : .
plugins_dir         : _plugins # takes an array of strings and loads plugins in that order
layouts_dir         : _layouts
data_dir            : _data
includes_dir        : _includes
sass:
  sass_dir: _sass
collections:
  posts:
    output          : true

# Handling Reading
safe                : false
include             : [".htaccess"]
exclude             : ["Gemfile", "Gemfile.lock", "node_modules", "vendor/bundle/", "vendor/cache/", "vendor/gems/", "vendor/ruby/"]
keep_files          : [".git", ".svn"]
encoding            : "utf-8"
markdown_ext        : "markdown,mkdown,mkdn,mkd,md"
strict_front_matter : false

# Filtering Content
show_drafts         : null
limit_posts         : 0
future              : false
unpublished         : false

# Plugins
whitelist           : []
plugins             : []

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

# Serving
detach              : false
port                : 4000
host                : 127.0.0.1
baseurl             : "" # does not include hostname
show_dir_listing    : false

# Outputting
permalink           : date
paginate_path       : /page:num
timezone            : null

quiet               : false
verbose             : false
defaults            : []

liquid:
  error_mode        : warn
  strict_filters    : false
  strict_variables  : false

# Markdown Processors
kramdown:
  auto_ids          : true
  entity_output     : as_char
  toc_levels        : [1, 2, 3, 4, 5, 6]
  smart_quotes      : lsquo,rsquo,ldquo,rdquo
  input             : GFM
  hard_wrap         : false
  footnote_nr       : 1
  show_warnings     : false

Front Matter 默认值

使用 front matter 是您可以在网站的页面和文章中指定配置的一种方式。设置默认布局、自定义标题或为文章指定更精确的日期/时间等内容都可以添加到您的页面或文章 front matter 中。

通常情况下，您会发现自己重复了很多配置选项。在每个文件中设置相同的布局，在文章中添加相同的 category 或 categories，等等。你甚至可以添加自定义变量，如作者姓名，这可能与你博客上的大多数文章相同。

Jekyll提供了一种在站点配置中设置这些默认值的方法，而不是在每次创建新文章或页面时重复此配置。为此，您可以使用项目根目录下 _config.yml 文件中的 defaults “键”来指定站点范围的默认值。

defaults "键"包含一组 scope/values 对，它们定义了应为特定文件路径设置的默认值，以及该路径中的文件类型（可选）。

假设您希望为站点中的所有页面和文章添加默认布局。您可以将这个添加到 _config.yml 文件中：

defaults:
  -
    scope:
      path: "" # an empty string here means all files in the project
    values:
      layout: "default"

停止并重新运行 jekyll serve 命令。

_config.yml 主配置文件包含全局配置和变量定义，它们在执行时读取一次。在自动重新生成过程中对 _config.yml 所做的更改直到下一次执行时才会加载。

注意 Data Files 会在自动重新生成过程中被重新加载和引入。

在这里，我们将 values 的范围限定在任何位于 path scope 的文件中。由于路径被设置为空字符串，因此它将应用于项目中的所有文件。您可能不想在项目中的每个文件上都设置布局，例如css文件，那么您也可以在 scope "键"下指定 type “值”。

defaults:
  -
    scope:
      path: "" # an empty string here means all files in the project
      type: "posts" # previously `post` in Jekyll 2.2.
    values:
      layout: "default"

现在，这将只为 type 为 posts 的文件设置布局。您可以使用的不同 types 包括 pages, posts, drafts 或 您网站中的任何 collection。虽然 type 是可选的，但在创建 scope/values 对时，必须为 path 指定一个值。

如前所述，您可以为 defaults 设置多个 scope/values 对。

defaults:
  -
    scope:
      path: ""
      type: "pages"
    values:
      layout: "my-site"
  -
    scope:
      path: "projects"
      type: "pages" # previously `page` in Jekyll 2.2.
    values:
      layout: "project" # overrides previous default layout
      author: "Mr. Hyde"

有了这些默认设置，所有页面都将使用 my-site 布局。projects/ 文件夹中存在的任何html文件都将使用 project 布局（如果存在）。这些文件的 page.author liquid variable 也将设置为 Mr. Hyde 。

collections:
  my_collection:
    output: true

defaults:
  -
    scope:
      path: ""
      type: "my_collection" # a collection in your site, in plural form
    values:
      layout: "default"

在本例中，layout 在名为 my_collection 的 collection 内被设置为 default 。

Front Matter 默认配置中的 Glob 模式

在匹配默认值时，也可以使用glob模式（目前仅限于包含 * 的模式）。例如，可以为 section 文件夹里任何子文件夹中的每个 special-page.html 设置特定布局。(3.7.0)

collections:
  my_collection:
    output: true

defaults:
  -
    scope:
      path: "section/*/special-page.html"
    values:
      layout: "specific-layout"

Globbing and Performance

请注意，众所周知，globbing 一个路径会对性能产生负面影响，目前尚未进行优化，尤其是在Windows上。Globbing 一个路径将增加您的构建时间，这与相关 collection 目录的大小成比例。

优先级

Jekyll将应用您在 _config.yml 文件 defaults 部分中指定的所有配置设置。通过为 scope 指定更具体的 path ，可以选择覆盖其他 scope/values 对 中的设置。

您可以在上面倒数第二个示例中看到这一点。首先，我们将默认页面布局设置为 my-site 。然后，使用一个更具体的路径，我们为 project 里 projects/ 路径中的页面设置默认布局。这可以通过您在页面或文章 front matter 中设置的任何值来实现。

最后，如果您通过在 _config.yml 文件中添加 defaults 部分来设置站点配置中的默认值，则可以在文章或页面文件中覆盖这些设置。您所需要做的就是在文章或页面 front matter 中指定设置。例如：

# 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 的 layout 将设置为 foobar 而不是 project ，并且当站点被构建时，author将设置为 John Smith 而不是 Mr. Hyde

Environments

在 build（或 serve ）参数中，可以指定一个 Jekyll 环境变量和值。然后，构建的时候会在内容中的任何条件语句中应用此值。

例如，假设您在代码中设置了以下条件语句：

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

当您构建Jekyll站点时，if 语句中的内容将不会运行，除非您还在 build 命令中指定了 production 环境变量，如下所示：

JEKYLL_ENV=production jekyll build

通过指定环境变量的值，可以使某些内容仅在特定环境中可用。

JEKYLL_ENV 的默认值是 development 。因此，如果您在构建参数中省略了 JEKYLL_ENV ，那么默认值将是 JEKYLL_ENV=development 。{% if jekyll.environment == "development" %} tags 中的任何内容都将自动出现在构建过程中。

您的环境变量值可以是您想要的任何值（不仅仅是 development 或 production ）。你可能想在开发环境中隐藏的一些元素包括Disqus评论表单或谷歌分析。相反，您可能希望在开发环境中公开 “Edit me in GitHub” 按钮，但不将其包含在生产环境中。

通过在 build 命令中指定该选项，可以避免在从一个环境移动到另一个环境时更改配置文件中的值。

注意：
要根据环境变量切换部分配置的设置，请使用 build命令选项 ，例如 --config _config.yml,_config_development.yml 。之后文件中的设置会覆盖之前文件中的设定。

Markdown 选项

Jekyll 支持的各种 Markdown 渲染器有时会提供额外的选项。

Kramdown

Kramdown 是 Jekyll 的默认 Markdown 渲染器，通常在没有额外配置的情况下运行良好。但是，它确实支持很多配置选项。

Kramdown Processor

默认情况下，Jekyll 为 Kramdown 使用 GitHub Flavored Markdown (GFM) processor 。（指定 input: GFM 很好，但是多余的。）GFM 支持几个额外的 Kramdown 选项，由 kramdown-parser-gfm 记录。这些选项可以直接在 Kramdown Jekyll 配置中使用，如下所示：

kramdown:
  gfm_quirks: [paragraph_end]

您还可以更改 Kramdown 使用的处理器（如为 Kramdown RDoc 中的 input "键"指定的）。例如，要在Jekyll中使用 non-GFM Kramdown 处理器，请将以下内容添加到您的配置中。

kramdown:
  input: Kramdown

Kramdown docs 中提供了 Kramdowns 解析器的文档。如果您使用的是 Kramdown 或 GFM 以外的 Kramdown 解析器，则需要为其添加 gem 。

语法高亮 (CodeRay)

要在 Kramdown 中使用 CodeRay 语法高亮，需要添加对 kramdown-syntax-coderay gem 的依赖项。例如，bundle add kramdown-syntax-coderay 。然后，您可以在 syntax_highlighter 配置中指定 CodeRay ：

kramdown:
  syntax_highlighter: coderay

CodeRay 支持几个自身的配置选项，这些选项记录在 kramdown-syntax-coderay docs ，可以作为 syntax_highlighter_opts 传递，如下所示：

kramdown:
  syntax_highlighter: coderay
  syntax_highlighter_opts:
    line_numbers: table
    bold_every: 5

高级 Kramdown 选项

Kramdown 支持各种其他相对高级的选项，如 header_offset 和 smart_quotes 。这些都记录在 Kramdown configuration documentation ，可以像这样添加到您的 Kramdown 配置中：

kramdown:
  header_offset: 2

有几个不受支持的 kramdown 选项

请注意，Jekyll使用的是 Kramdown 的 HTML 转换器。仅由其他转换器使用的 Kramdown 选项，如 remove_block_html_tags（由RemoveHtmlTags 转换器使用），将不起作用。

CommonMark

CommonMark 是Markdown语法的合理化版本，用C语言实现，因此比用Ruby实现的默认 Kramdown 更快。它与原始的 Markdown 略有不同 ，并不支持在 Kramdown 中实现的全部语法元素，如 Block Inline Attribute Lists 。

它有两种风格：带有 jekyll-commonmark 插件的基本 CommonMark 和 GitHub Pages 支持的GitHub风格的Markdown 。

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

Liquid 选项

Liquid 对错误的响应可以通过设置 error_mode 来配置。选项包括

• lax — 忽略所有错误。
• warn — 在控制台上为每个错误输出一个警告。（默认值）
• strict — 输出一条错误消息并停止构建。

在 _config.yml 中，默认配置如下：

liquid:
  error_mode: warn

上面的例子描述了 “warn” 值，默认情况下已经设置了 - error_mode: warn 。这会导致在构建过程中任何问题都将被调出，但如果可能的话，将继续构建。

还可以通过将 strict_variables 和/或 strict_filters 分别设置为 true ，将 Liquid 的渲染器配置为捕获未分配的变量和不存在的 filters。(3.8.0)

请注意，当在 error_mode 下配置 Liquid 的解析器时，strict_variables 和 strict_filters 选项配置 Liquid 的渲染器，因此是正交的。

在 _config.yml 中设置这些变量的示例如下：

liquid:
  error_mode: strict
  strict_variables: true
  strict_filters: true

按如上所述进行配置将停止 build/serve ，并调出有问题的错误，然后停止。当您希望通过停止 build 或 serve 过程来发现与 liquid 相关的问题，并允许您处理任何问题时，这是很有帮助的。

Sass/SCSS 选项

Jekyll 与 jekyll-sass-converter 插件捆绑在一起。默认情况下，Jekyll将在相对于站点 source 目录的 _sass 目录中查找 Sass 部分。

您可以通过在 sass 属性下的Jekyll配置中添加选项来进一步配置插件。有关详细信息及其默认值，请参阅 plugin’s documentation 。

请注意，sass 配置中指定的目录路径是相对于站点的 source 解析的，而不是相对于 _config.yml 文件的位置解析的。

WEBrick 选项

您可以通过将标题添加到 _config.yml 来为您的网站提供自定义标题

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

默认值

Jekyll 默认提供 Content-Type 和 Cache-Control 响应标头：一个是动态的，用于指定网站运行中数据的性质，另一个是静态的，用于禁用缓存，这样在开发模式下就不必与Chrome的激进缓存作斗争。

Incremental Regeneration

增量再生仍然是一个试验性的特征

虽然增量再生适用于最常见的情况，但它不会在所有情况下都正确工作。使用该功能时请格外谨慎，并通过 在GitHub上报告问题 报告以下未列出的任何问题。

增量重新生成只构建自上次构建以来被更新的文档和页面，这有助于缩短构建时间。它通过跟踪 .jekyll-metadata 文件中的文件修改时间和文档间依赖关系来实现这一点。

在当前的实现中，增量重新生成只会在文档或页面或其依赖项之一被修改时生成文档或页面。目前，被跟踪的唯一依赖项类型是 include（使用 {% include %} tag）和 layouts 。这意味着对其他文档的普通引用（例如，一种常见情况是，在文章列表页面中迭代 site.posts ）将不会被检测为依赖项。

为了弥补其中的一些不足，将 regenerate: true 放在文档的 front-matter ，将迫使Jekyll重新生成它，无论它是否被修改。请注意，这将仅生成指定的文档；对其他文档内容的引用将不起作用，因为它们不会被重新渲染。

可以通过命令行中的 --incremental 标志（简称 -I ）或在配置文件中设置 incremental: true 来启用增量重新生成。

😄返回目录