Jekyll 配置完全指南：_config.yml、命令行标志与 Front Matter 默认值深度解析

Jekyll 配置完全指南：_config.yml、命令行标志与 Front Matter 默认值深度解析

【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll

本文以 Jekyll（Ruby 编写的博客感知型静态站点生成器）官方配置文档为骨架，系统讲解 Jekyll 的全部配置入口：站点根目录下的_config.yml（或_config.toml）配置文件、jekyll可执行文件的命令行标志，以及可嵌入页面本身的 Front Matter 默认值机制。你将掌握全局配置、构建/服务命令选项、环境切换、Markdown/Liquid/Sass/WEBrick 专项配置与增量重建的完整用法，并理解配置在 lib/jekyll/configuration.rb 中的加载、合并与校验流程——读完即可为自己的站点写出准确、可复用的配置。

一、配置的三种来源与合并顺序

Jekyll 给予你很大的灵活性来自定义站点的构建方式。这些选项可以通过以下三种方式提供：

1. 配置文件：在站点根目录放置_config.yml或_config.toml；
2. 命令行标志：在执行jekyll可执行文件时以 flag 形式传入；
3. Front Matter：在每个页面/文章的 YAML 头信息中声明（详见下文"Front Matter 默认值"一节）。

从源码看，Jekyll 的配置加载遵循"默认值 → 配置文件 → 命令行覆盖"的合并链。lib/jekyll/configuration.rb 中定义了一份冻结的DEFAULTS哈希（字符串键，兼容 YAML），Configuration.from通过Utils.deep_merge_hashes(DEFAULTS, user_config)完成合并，再调用add_default_collections与add_default_excludes补全默认集合与排除项。

配置文件本身的探测逻辑也值得注意（configuration.rb）：

• 若命令行未指定--config，Jekyll 会在站点source目录下依次查找_config.yml、_config.yaml、_config.toml，命中第一个存在者；
• 文件后缀决定解析器：.toml由Tomlrb解析，.ya?ml由SafeYAML解析（configuration.rb）；
• 若显式指定了--config FILE1,FILE2,...，多个配置文件会按顺序读取，并通过Utils.deep_merge_hashes逐层深合并——后出现的文件覆盖先出现的文件，这常用于按环境拆分配置（见下文"环境"一节）。

多个配置文件组合示例

jekyll build --config _config.yml,_config_development.yml

二、全局配置选项（Global Configuration）

下表汇总 Jekyll 的全局设置：option列是配置文件中的写法，flag列是对应的命令行写法。

设置项	配置写法	命令行标志	说明
站点源目录	source: DIR	-s, --source DIR	修改 Jekyll 读取文件的目录
站点输出目录	destination: DIR	-d, --destination DIR	修改 Jekyll 写入文件的目录
安全模式	safe: BOOL	--safe	禁用非白名单插件、磁盘缓存并忽略符号链接
禁用磁盘缓存 (4.1.0+)	disable_disk_cache: BOOL	--disable-disk-cache	不在源码目录创建.jekyll-cache等缓存目录，避免干扰虚拟环境与第三方目录监听器；safe模式下磁盘缓存总是被禁用
忽略主题配置 (4.1.0+)	ignore_theme_config: BOOL	—	Jekyll 4.0 起允许主题自带_config.yml；当导入的主题配置破坏合并结果时，可设置为true完全不导入
排除项	exclude: [DIR, FILE, ...]	—	从转换中排除目录/文件，相对站点源目录且不能越界
包含项	include: [DIR, FILE, ...]	—	强制包含目录/文件（如默认被排除的.htaccess点文件）
保留文件	keep_files: [DIR, FILE, ...]	—	清理输出目录时保留指定文件，适用于非 Jekyll 生成的构建产物，路径相对destination
时区	timezone: TIMEZONE	—	设置站点生成时区（写入TZ环境变量），取值来自 IANA 时区数据库，如America/New_York
编码	encoding: ENCODING	—	按名称设置文件编码，2.0.0 起默认utf-8

exclude 与 include 的版本差异（重点）

exclude支持 RubyFile.fnmatch文件名通配模式，可一次匹配多个条目。例如排除源码树中所有README.md：

exclude: - README.md - "**/README.md"

版本行为有重要差异：

• Jekyll 3：exclude会替换默认排除列表；
• Jekyll 4：用户条目会追加到默认排除列表，且include中的条目可以覆盖默认排除列表条目。

Jekyll 4 由jekyll new生成的_config.yml自带默认排除项：

exclude: - .sass-cache/ - .jekyll-cache/ - gemfiles/ - Gemfile - Gemfile.lock - node_modules/ - vendor/bundle/ - vendor/cache/ - vendor/gems/ - vendor/ruby/

⚠️ 输出目录清理警告

站点构建时，<destination>目录的内容默认会被自动清理：凡不是站点生成的文件/文件夹都会被删除。因此：

• 需要保留的第三方构建产物，务必写入keep_files配置；
• 不要把重要目录用作destination，应将其作为暂存区，构建后再把文件复制到 Web 服务器。

目录路径约定

一般情况下，plugins_dir等配置键中的目录路径应相对当前工作目录而非站点源目录；唯一的例外是sass配置键，其值必须相对站点源目录。

三、默认配置全解

Jekyll 以如下选项为默认值运行；你可以在配置文件或命令行中显式覆盖它们（完整默认值见 docs/_docs/configuration/default.md，与源码DEFAULTS一致）：

# Where things are（目录位置） source : . destination : ./_site collections_dir : . plugins_dir : _plugins # 可传字符串数组，按顺序加载插件 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 : "" # 不含主机名 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（Markdown 处理器） 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

逐段要点：

• 目录位置：source默认当前目录，destination默认./_site；collections中内置了posts集合并开启output: true。源码还定义了cache_dir: ".jekyll-cache"（configuration.rb）。
• 读取处理：默认只包含.htaccess，默认排除 Gemfile 相关、node_modules与vendor/*下的依赖目录；keep_files默认保留.git与.svn。
• 内容过滤：show_drafts: null表示默认不渲染草稿，limit_posts: 0表示不限量，future: false不发布未来日期的文章，unpublished: false不渲染标记为未发布的文章。
• 转换：默认 Markdown 处理器为kramdown、语法高亮为rouge，excerpt_separator默认"\n\n"。
• 服务：默认端口4000、绑定127.0.0.1，baseurl为空（挂载在根路径）。
• 输出：permalink: date即/年/月/日/标题/风格的链接；paginate_path默认/page:num。

配置文件格式禁忌

切勿在配置文件中使用 Tab 缩进——这要么导致解析错误，要么让 Jekyll 静默回退到默认设置。请始终使用空格。

四、构建命令选项（Build Command Options）

下表为jekyll build支持的选项，均可在配置文件（option）与命令行（flag）中指定：

设置项	配置写法	命令行标志	说明
监听重建	—	-w, --[no-]watch	文件变更时自动重建站点
配置文件	—	--config FILE1[,FILE2,...]	指定配置文件；后列文件覆盖前列
插件目录	plugins_dir: [DIR1,...]	-p, --plugins DIR1[,DIR2,...]	指定插件目录，替代默认_plugins/
布局目录	layouts_dir: DIR	--layouts DIR	指定布局目录，替代默认_layouts/
草稿	show_drafts: BOOL	-D, --drafts	处理并渲染草稿文章
环境	—	JEKYLL_ENV=production	在构建中使用指定环境值（见"环境"一节）
未来文章	future: BOOL	--future	发布未来日期的文章/集合文档
未发布文章	unpublished: BOOL	--unpublished	渲染标记为未发布的文章
LSI 相关文章	lsi: BOOL	--lsi	生成相关文章索引，需 classifier-reborn 插件
限制文章数	limit_posts: NUM	--limit_posts NUM	限制解析与发布的文章数量
强制轮询	force_polling: BOOL	--force_polling	强制 watch 使用轮询机制
详细输出	verbose: BOOL	-V, --verbose	打印详细输出
静默输出	quiet: BOOL	-q, --quiet	构建时静默 Jekyll 的正常输出
日志级别	—	JEKYLL_LOG_LEVEL=info	取debug、info、warn、error之一
增量构建	incremental: BOOL	-I, --incremental	启用实验性增量构建，只重建变更的页面（详见"增量重建"一节）
禁止 Bundler 加载	—	JEKYLL_NO_BUNDLER_REQUIRE=true	不自动 require:jekyll_plugins组的 gem
Liquid 剖析	profile: BOOL	--profile	生成 Liquid 渲染剖析，定位性能瓶颈
严格 Front Matter	strict_front_matter: BOOL	--strict_front_matter	页面 Front Matter 出现 YAML 语法错误时让构建失败
站点根 URL	url: SCHEME://HOST[:PORT]	—	生产部署根地址（协议 + 主机名 + 可选端口），不应带尾部斜杠，与baseurl拼接后供absolute_url过滤器使用；jekyll serve时自动设为 localhost URL
基础 URL	baseurl: /PATH/TO/SITE	-b, --baseurl /PATH/TO/SITE	从域名根到落地页之间的路径，如站点部署在子目录时
完整堆栈	—	-t, --trace	出错时输出完整 backtrace

这些选项同样整理在 docs/_data/config_options/build.yml，由 docs/_docs/configuration/options.md 渲染成表。

五、服务命令选项（Serve Command Options）

jekyll serve除下列专属选项外，还接受build的全部选项——它们会被应用到服务启动前的那次站点构建上（完整清单见 docs/_data/config_options/serve.yml）：

设置项	配置写法	命令行标志	说明
端口	port: PORT	-P, --port PORT	监听端口，默认4000
主机名	host: HOSTNAME	-H, --host HOSTNAME	监听主机名，默认localhost
实时重载	livereload: BOOL	-l, --livereload	内容编辑后浏览器自动刷新页面
实时重载忽略	livereload_ignore: [GLOB1,...]	--livereload-ignore GLOB1[,GLOB2,...]	LiveReload 忽略的文件 glob；命令行传入时务必加引号防止 shell 展开；模式针对资源的relative_path属性匹配
实时重载延时	livereload_min_delay/livereload_max_delay（秒）	--livereload-min-delay/--livereload-max-delay	自动重载的最小/最大延迟
实时重载端口	livereload_port: PORT	--livereload-port PORT	LiveReload 监听端口；配置文件方式 4.4.0 起支持
打开 URL	open_url: BOOL	-o, --open-url	启动后在浏览器中打开站点 URL
分离运行	detach: BOOL	-B, --detach	服务与终端分离（后台运行）
跳过首次构建	skip_initial_build: BOOL	--skip-initial-build	跳过服务启动前的那次站点构建
目录列表	show_dir_listing: BOOL	--show-dir-listing	显示目录列表而非加载 index 文件
SSL 私钥	—	--ssl-key	X.509 私钥，存放或软链接于站点源目录
SSL 证书	—	--ssl-cert	X.509 公钥证书，存放或软链接于站点源目录

组合示例：带实时重载与 SSL 的服务

jekyll serve --livereload --host 0.0.0.0 --port 8080

六、Front Matter 默认值（Front Matter Defaults）

Front Matter 是在页面与文章中指定配置的一种方式：默认布局、自定义标题、更精确的日期时间等都可以写进每篇文件的 Front Matter。但你会发现大量配置（同一布局、相同分类、相同的自定义变量如作者名）被反复书写。

Jekyll 提供了在站点配置中统一定义这些默认值的机制：使用_config.yml根目录下的defaults键。它保存一组scope/values 对——scope定义该默认值作用于哪个文件路径（可选文件类型），values定义要施加的默认配置。

基础用法：为所有文件设置默认布局

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

限定文件类型

只对posts类型生效（Jekyll 2.2 之前写作post）：

defaults: - scope: path: "" # 空字符串表示项目中的所有文件 type: "posts" # Jekyll 2.2 之前写作 `post` values: layout: "default"

可用的type有pages、posts、drafts，或站点中的任意集合。type可选，但只要建立 scope/values 对就必须指定path。

多个 scope/values 对与更具体的路径

defaults: - scope: path: "" type: "pages" values: layout: "my-site" - scope: path: "projects" type: "pages" # Jekyll 2.2 之前写作 `page` values: layout: "project" # 覆盖前面的默认布局 author: "Mr. Hyde"

此时所有页面默认使用my-site布局；projects/目录下的 HTML 文件改用project布局（若存在），且其page.authorLiquid 变量被设为Mr. Hyde。

作用于集合

collections: my_collection: output: true defaults: - scope: path: "" type: "my_collection" # 站点中的集合，使用复数形式 values: layout: "default"

使用 glob 模式（3.7.0+）

defaults的路径匹配支持含*的 glob 模式。例如为section文件夹任意子文件夹中的每个special-page.html设置专属布局：

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

⚠️性能提示：glob 化路径已知会带来性能开销且目前未做优化（Windows 上尤其明显），构建耗时会随关联集合目录的体积成比例增长，请谨慎使用。

优先级（Precedence）

1. defaults中所有 scope/values 对都会被应用；
2. 更具体的 path 覆盖更宽泛的 path（如上面的projects覆盖空路径）；
3. 页面/文章自身的 Front Matter 覆盖一切defaults设置。

后两级的覆盖示例：

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

# 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）。

⚠️ 修改 _config.yml 后需重启 serve

_config.yml主配置文件中的全局配置与变量定义只在执行时读取一次。自动重建期间对_config.yml的修改不会在下次重建前被加载——请停止并重新运行jekyll serve。相比之下，Data Files 在自动重建期间会被重新加载。

七、环境（Environments）

在build（或serve）参数中可以指定一个 Jekyll 环境值，构建时该值会注入jekyll.environment，供内容中的条件语句使用：

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

只有显式传入production环境时，上述内容才会被构建：

JEKYLL_ENV=production jekyll build

• 未指定时JEKYLL_ENV默认为development，因此{% if jekyll.environment == "development" %}内的内容默认就会出现在构建中；
• 环境值可以是任意字符串，不限于development/production；
• 典型场景：开发环境隐藏 Disqus 评论或 Google Analytics，生产环境隐藏"在 GitHub 上编辑"按钮等；
• 通过在构建命令中指定环境，避免了在不同环境间迁移时修改配置文件的值。

若希望配置本身也随环境切换，请使用构建命令选项，例如--config _config.yml,_config_development.yml——后列文件的设置覆盖前列文件的设置。

八、Markdown 选项（Markdown Options）

Jekyll 支持的 Markdown 渲染器各自带有额外选项，详见 docs/_docs/configuration/markdown.md。

Kramdown（默认渲染器）

Kramdown 是 Jekyll 的默认 Markdown 渲染器，通常无需额外配置即可良好工作，但它支持大量选项。

GFM 处理器：默认情况下 Jekyll 使用 Kramdown 的 GitHub Flavored Markdown (GFM) 处理器（显式写input: GFM并无不可，只是冗余）。GFM 还支持若干额外选项，可直接写入 Kramdown 配置：

kramdown: gfm_quirks: [paragraph_end]

切换处理器：通过input键可更换 Kramdown 使用的处理器。例如改用非 GFM 的 Kramdown 处理器：

kramdown: input: Kramdown

若使用 Kramdown 与 GFM 之外的其他解析器，需要额外安装对应 gem。

CodeRay 语法高亮：要与 Kramdown 配合使用 CodeRay 高亮器，先添加依赖：bundle add kramdown-syntax-coderay，然后指定：

kramdown: syntax_highlighter: coderay

CodeRay 还支持自己的选项，通过syntax_highlighter_opts传入：

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

高级选项：如header_offset、smart_quotes等相对高级的选项同样支持：

kramdown: header_offset: 2

⚠️注意：Jekyll 使用 Kramdown 的HTML 转换器。仅被其他转换器使用的 Kramdown 选项（如 RemoveHtmlTags 转换器所用的remove_block_html_tags）不会生效。

CommonMark

CommonMark 是 Markdown 语法的合理化版本，以 C 实现、比 Ruby 实现的默认 Kramdown 更快。它与原始 Markdown 略有差异，且不支持 Kramdown 的全部语法元素（如 Block Inline Attribute Lists）。它有两大风味：基于 jekyll-commonmark 插件的基础 CommonMark，以及 GitHub Pages 使用的 GFM 版本。

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

Liquid 对错误的响应可通过error_mode配置（默认warn）：

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

liquid: error_mode: warn

此外，可将strict_variables与/或strict_filters设为true（3.8.0+），让渲染器捕获未赋值变量与不存在的过滤器：

liquid: error_mode: strict strict_variables: true strict_filters: true

注意二者与error_mode是正交的：error_mode配置的是 Liquid解析器，而strict_variables/strict_filters配置的是 Liquid渲染器。按上述配置后，任何 Liquid 相关错误都会中止 build/serve，便于你集中排查模板问题。

十、Sass/SCSS 选项（Sass/SCSS Options）

Jekyll 内置 jekyll-sass-converter 插件。默认情况下，Jekyll 会在站点source目录下的_sass目录中查找 Sass 部分文件（partials）。可通过sass属性进一步配置：

sass: sass_dir: _sass

要点：

• sass配置中的目录路径相对站点source目录解析，而非_config.yml所在位置（这是前文"目录路径约定"中提到的唯一例外）；
• VSCode 对@import "main";的警告可以忽略，不影响 Jekyll 中 SCSS 的功能；但 Jekyll 4不允许从同名 Sass 页面（如css/main.scss）导入_sass/main.scss这一同名 partial。

十一、WEBrick 选项（WEBrick Options）

通过webrick.headers可为站点提供自定义响应头：

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

默认情况下 Jekyll 会提供两个响应头：动态的Content-Type（说明所服务数据的性质）与静态的Cache-Control（禁用缓存，避免开发模式下与 Chrome 的激进缓存作斗争）。

十二、增量重建（Incremental Regeneration）

增量重建通过只生成自上次构建以来更新过的文档与页面来缩短构建时间。它借助.jekyll-metadata文件同时跟踪文件修改时间与文档间依赖关系。

• 当前实现下，只有文档自身或其依赖被修改时才会重新生成。目前跟踪的依赖类型仅有：{% include %}标签的包含文件，以及布局（layouts）。因此，对其他文档的普通引用（例如在文章列表页遍历site.posts）不会被识别为依赖；
• 为弥补上述不足，可在文档 Front Matter 中设置regenerate: true强制 Jekyll 重新生成该文档（仅限该文档本身，其他文档的内容引用不会因重新渲染而更新）；
• 启用方式：命令行--incremental（简写-I），或配置文件incremental: true。

⚠️实验性特性警告：增量重建仍是实验性功能。它对大多数常见场景有效，但并非在所有场景下都正确。请极其谨慎地使用，并将文中未列出的问题提交到 Jekyll 的 issue 跟踪器。

结语：从配置到构建的完整链路

至此，你已掌握 Jekyll 配置的三大入口（_config.yml/_config.toml、命令行标志、Front Matter 默认值）与合并覆盖规则；理解了全局、构建、服务三大类选项的完整清单与默认值；并学会了按环境拆分配置、定制 Markdown/Liquid/Sass/WEBrick 行为以及启用增量重建。配置层的完整选项数据沉淀在 docs/_data/config_options/，合并与校验逻辑在 lib/jekyll/configuration.rb，结合 docs/_docs/configuration/default.md 中的默认值清单，你可以随时对照排查自己的站点配置问题。

【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll