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本文以 JekyllRuby 编写的博客感知型静态站点生成器官方配置文档为骨架系统讲解 Jekyll 的全部配置入口站点根目录下的_config.yml或_config.toml配置文件、jekyll可执行文件的命令行标志以及可嵌入页面本身的 Front Matter 默认值机制。你将掌握全局配置、构建/服务命令选项、环境切换、Markdown/Liquid/Sass/WEBrick 专项配置与增量重建的完整用法并理解配置在 lib/jekyll/configuration.rb 中的加载、合并与校验流程——读完即可为自己的站点写出准确、可复用的配置。一、配置的三种来源与合并顺序Jekyll 给予你很大的灵活性来自定义站点的构建方式。这些选项可以通过以下三种方式提供配置文件在站点根目录放置_config.yml或_config.toml命令行标志在执行jekyll可执行文件时以 flag 形式传入Front Matter在每个页面/文章的 YAML 头信息中声明详见下文Front Matter 默认值一节。从源码看Jekyll 的配置加载遵循默认值 → 配置文件 → 命令行覆盖的合并链。lib/jekyll/configuration.rb 中定义了一份冻结的DEFAULTS哈希字符串键兼容 YAMLConfiguration.from通过Utils.deep_merge_hashes(DEFAULTS, user_config)完成合并再调用add_default_collections与add_default_excludes补全默认集合与排除项。配置文件本身的探测逻辑也值得注意configuration.rb若命令行未指定--configJekyll 会在站点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-8exclude 与 include 的版本差异重点exclude支持 RubyFile.fnmatch文件名通配模式可一次匹配多个条目。例如排除源码树中所有README.mdexclude: - README.md - **/README.md版本行为有重要差异Jekyll 3exclude会替换默认排除列表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 ProcessorsMarkdown 处理器 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默认./_sitecollections中内置了posts集合并开启output: true。源码还定义了cache_dir: .jekyll-cacheconfiguration.rb。读取处理默认只包含.htaccess默认排除 Gemfile 相关、node_modules与vendor/*下的依赖目录keep_files默认保留.git与.svn。内容过滤show_drafts: null表示默认不渲染草稿limit_posts: 0表示不限量future: false不发布未来日期的文章unpublished: false不渲染标记为未发布的文章。转换默认 Markdown 处理器为kramdown、语法高亮为rougeexcerpt_separator默认\n\n。服务默认端口4000、绑定127.0.0.1baseurl为空挂载在根路径。输出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_ENVproduction在构建中使用指定环境值见环境一节未来文章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_LEVELinfo取debug、info、warn、error之一增量构建incremental: BOOL-I, --incremental启用实验性增量构建只重建变更的页面详见增量重建一节禁止 Bundler 加载—JEKYLL_NO_BUNDLER_REQUIREtrue不自动 require:jekyll_plugins组的 gemLiquid 剖析profile: BOOL--profile生成 Liquid 渲染剖析定位性能瓶颈严格 Front Matterstrict_front_matter: BOOL--strict_front_matter页面 Front Matter 出现 YAML 语法错误时让构建失败站点根 URLurl: SCHEME://HOST[:PORT]—生产部署根地址协议 主机名 可选端口不应带尾部斜杠与baseurl拼接后供absolute_url过滤器使用jekyll serve时自动设为 localhost URL基础 URLbaseurl: /PATH/TO/SITE-b, --baseurl /PATH/TO/SITE从域名根到落地页之间的路径如站点部署在子目录时完整堆栈—-t, --trace出错时输出完整 backtrace这些选项同样整理在 docs/_data/config_options/build.yml由 docs/_docs/configuration/options.md 渲染成表。五、服务命令选项Serve Command Optionsjekyll 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 PORTLiveReload 监听端口配置文件方式 4.4.0 起支持打开 URLopen_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-keyX.509 私钥存放或软链接于站点源目录SSL 证书—--ssl-certX.509 公钥证书存放或软链接于站点源目录组合示例带实时重载与 SSL 的服务jekyll serve --livereload --host 0.0.0.0 --port 8080六、Front Matter 默认值Front Matter DefaultsFront Matter 是在页面与文章中指定配置的一种方式默认布局、自定义标题、更精确的日期时间等都可以写进每篇文件的 Front Matter。但你会发现大量配置同一布局、相同分类、相同的自定义变量如作者名被反复书写。Jekyll 提供了在站点配置中统一定义这些默认值的机制使用_config.yml根目录下的defaults键。它保存一组scope/values 对——scope定义该默认值作用于哪个文件路径可选文件类型values定义要施加的默认配置。基础用法为所有文件设置默认布局defaults: - scope: path: # 空字符串表示项目中的所有文件 values: layout: default限定文件类型只对posts类型生效Jekyll 2.2 之前写作postdefaults: - 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.0defaults的路径匹配支持含*的 glob 模式。例如为section文件夹任意子文件夹中的每个special-page.html设置专属布局collections: my_collection: output: true defaults: - scope: path: section/*/special-page.html values: layout: specific-layout⚠️性能提示glob 化路径已知会带来性能开销且目前未做优化Windows 上尤其明显构建耗时会随关联集合目录的体积成比例增长请谨慎使用。优先级Precedencedefaults中所有 scope/values 对都会被应用更具体的 path 覆盖更宽泛的 path如上面的projects覆盖空路径页面/文章自身的 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_ENVproduction jekyll build未指定时JEKYLL_ENV默认为development因此{% if jekyll.environment development %}内的内容默认就会出现在构建中环境值可以是任意字符串不限于development/production典型场景开发环境隐藏 Disqus 评论或 Google Analytics生产环境隐藏在 GitHub 上编辑按钮等通过在构建命令中指定环境避免了在不同环境间迁移时修改配置文件的值。若希望配置本身也随环境切换请使用构建命令选项例如--config _config.yml,_config_development.yml——后列文件的设置覆盖前列文件的设置。八、Markdown 选项Markdown OptionsJekyll 支持的 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: coderayCodeRay 还支持自己的选项通过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不会生效。CommonMarkCommonMark 是 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 OptionsLiquid 对错误的响应可通过error_mode配置默认warnlax—— 忽略所有错误warn—— 每个错误在控制台输出警告默认strict—— 输出错误信息并停止构建。liquid: error_mode: warn此外可将strict_variables与/或strict_filters设为true3.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 OptionsJekyll 内置 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考