Jekyll 2.2.0 版本解析布局缺失告警、安全模式高亮白名单与文章路径分类支持【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyllJekyll 2.2.0 是 2014 年 7 月发布的一个小版本更新聚焦于构建流程的健壮性与安全模式safe mode下代码高亮的可用性。本篇文章以 官方发布公告 为骨架结合当前仓库中的 History.markdown 变更记录与 lib/ 源码实现深入讲解“布局缺失告警”“Pygments 选项安全白名单”与“_posts路径分类”三项核心更新并给出可直接实践的配置与验证方式。读完本文你将理解这三项改动的触发条件、底层实现原理及在站点构建中的实际影响。一、发布背景与版本定位Jekyll 2.2.0 于 2014-07-29 发布由维护者 parkr 撰写发布公告。它是一个小版本minor功能更新不涉及破坏性变更主要包括三项关键更新在页面或文章的 front matter 中指定一个不存在的 layout 时构建过程将输出警告warning安全模式safe mode下Pygments 的部分选项被纳入白名单允许继续使用文章posts所在路径中的目录结构现在会被正确识别为分类categories即_posts下的子文件夹开始正常工作。发布公告同时指向完整的变更列表历史页面 中对应v2.2.0一节。在当前仓库的 History.markdown 中可以找到与公告一一对应的完整条目Minor EnhancementsThrow a warning if the specified layout does not exist (#2620)、Whitelist Pygments options in safe mode (#2642)Bug FixesRemove unnecessary Jekyll::Tags::IncludeTag#blank? method (#2625)、Categories in the path are ignored (#2633)以及若干开发与站点维护性修复如用 html-proofer 校验站点、更新第三方插件列表等。二、核心更新一缺失布局告警2.1 改动内容在此之前如果某个页面或文章的 front matter 里写了layout: my-layout而_layouts/目录中并不存在该布局文件Jekyll 会静默忽略并直接渲染页面正文用户很难察觉布局配置写错了。2.2.0 起构建过程会在这种情况下输出一条构建警告。2.2 当前源码实现这一行为延续至今实现在 lib/jekyll/renderer.rb。Renderer#place_in_layouts先从文档数据中取出 layout 名称并调用validate_layout校验def place_in_layouts(content, payload, info) output content.dup layout layouts[document.data[layout].to_s] validate_layout(layout) # ... 循环渲染 layout 链 end # Checks if the layout specified in the document actually exists def validate_layout(layout) return unless invalid_layout?(layout) Jekyll.logger.warn Build Warning:, Layout #{document.data[layout]} requested \ in #{document.relative_path} does not exist. end从源码可以看出两个细节告警消息会明确包含文档的相对路径document.relative_path方便快速定位是哪个文件写错了 layout校验发生在渲染链路入口place_in_layouts也就是说无论 layout 缺失与否页面内容仍会被渲染输出告警不会中断构建这与 Jekyll 一贯“尽量完成构建、同时把问题暴露给用户”的设计一致。2.3 布局的加载机制要理解“layout 不存在”判定需要看布局如何被读取。布局由 lib/jekyll/readers/layout_reader.rb 统一扫描它遍历layouts_dir默认_layouts以及主题theme的布局目录用layout_name去掉扩展名作为键存入layouts哈希def read layout_entries.each do |layout_file| layouts[layout_name(layout_file)] \ Layout.new(site, layout_directory, layout_file) end theme_layout_entries.each do |layout_file| layouts[layout_name(layout_file)] || \ Layout.new(site, theme_layout_directory, layout_file) end layouts end def layout_name(file) file.split(.)[0..-2].join(.) end因此layout: default对应的查找键是default它匹配_layouts/default.html或default.md等任意扩展名的文件。当 front matter 中的 layout 名称与任何一个已加载布局的键都不匹配时就会触发 2.2.0 引入的告警。2.4 实操验证以一个极简示例复现该告警在站点根目录创建_layouts/目录放入一个simple.html布局创建一篇文章_posts/2024-01-01-hello.mdfront matter 写为layout: no_such_layout执行构建jekyll build构建仍会成功完成但终端会输出类似如下的警告Build Warning: Layout no_such_layout requested in _posts/2024-01-01-hello.md does not exist.这对于排查“页面样式/结构没生效但构建又没报错”的问题非常实用。配套的回归测试覆盖于 test/test_renderer.rb 等渲染相关测试中可作进一步参考。三、核心更新二安全模式下 Pygments 选项白名单3.1 改动内容Jekyll 的--safe安全模式用于在不可信环境如 GitHub Pages 或插件沙箱中禁用自定义插件与部分危险特性。2.2.0 之前安全模式会对代码高亮标签{% highlight %}的可用选项做严格限制本次更新将部分 Pygments 选项纳入白名单使安全模式下的代码高亮仍然可用且可控PR #2642。3.2 代码高亮标签的现状需要说明的是当前仓库的 Jekyll 版本已默认使用 Rouge 作为高亮器Pygments 渲染路径已降级为回退并提示改用 Rouge。在 lib/jekyll/tags/highlight.rb 中def render(context) # ... output case context.registers[:site].highlighter when rouge render_rouge(code) when pygments render_pygments(code, context) else render_codehighlighter(code) end # ... end def render_pygments(code, _context) Jekyll.logger.warn Warning:, Highlight Tag no longer supports rendering with Pygments. Jekyll.logger.warn , Using the default highlighter, Rouge, instead. render_rouge(code) end也就是说即使在配置中指定highlighter: pygments当前版本也会输出警告并回退到 Rouge。2.2.0 时代的 Pygments 白名单属于当时的历史行为其精神延续到今天的 Rouge 实现中highlight标签的选项解析parse_options会按照固定的语法规则提取linenos、mark_lines3 4 5等选项未在白名单/语法内的写法会直接抛出 SyntaxError 而非悄悄执行SYNTAX %r!^([a-zA-Z0-9.#_-])((\s\w((\w|([0-9]\s)*[0-9]))?)*)$!.freeze def initialize(tag_name, markup, tokens) super if markup.strip ~ SYNTAX lang Regexp.last_match(1).downcase highlight_options parse_options(Regexp.last_match(2)) else raise SyntaxError, ~MSG Syntax Error in tag highlight while parsing the following markup: ... Valid syntax: highlight lang [linenos] [mark_lines3 4 5] MSG end end3.3 安全模式下的现代实践在今天的 Jekyll 中安全模式下使用代码高亮的推荐方式依赖默认高亮器Rougehighlighter: rouge它原生支持白名单化的语言与选项解析在_config.yml中通过markdown/kramdown.syntax_highlighter等相关配置声明高亮器使用标准语法书写代码块{% highlight ruby linenos %} def hello puts world end {% endhighlight %}linenos会启用行号内部归一化为inline行号形式mark_lines3 4 5可高亮指定行。这些选项的解析逻辑均可追溯到 lib/jekyll/tags/highlight.rb并有 test/test_tag_highlight.rb 提供行为保证。四、核心更新三_posts路径中的分类识别4.1 改动内容2.2.0 修复了一个长期存在的 bug#2633以前_posts下的子文件夹如_posts/es/2014-01-01-x.markdown中的目录名会被忽略从 2.2.0 开始这些目录名会被正确提取为该文章的 categories。4.2 当前源码实现该逻辑今天位于 lib/jekyll/document.rb。Document#populate_categories会合并三类来源从文件路径中提取的目录名categories_from_pathfront matter 中的category字段转为数组front matter 中的categories字段数组或逗号分隔。路径提取的核心是categories_from_path# Add superdirectories of the special_dir to categories. # In the case of es/_posts, es is added as a category. # In the case of _posts/es, es is NOT added as a category. def categories_from_path(special_dir) if relative_path.start_with?(special_dir) superdirs [] else superdirs relative_path.sub(Document.superdirs_regex(special_dir), ) superdirs superdirs.split(File::SEPARATOR) superdirs.reject! { |c| c.empty? || c special_dir || c basename } end merge_data!({ categories superdirs }, :source file path) end注意注释中特别强调的两个方向性差异es/_posts/..._posts前有目录→ 该目录es会被加入 categories_posts/es/..._posts内建子目录→ 该目录es不会被加入 categories这是刻意设计避免与默认:categories占位符产生歧义。4.3 与 front matter 分类的合并规则populate_categories会把路径分类与 front matter 分类合并并去重def populate_categories categories Array(data[categories]) Utils.pluralized_array_from_hash( data, category, categories ) categories.map!(:to_s) categories.flatten! categories.uniq! merge_data!({ categories categories }) end因此“目录名 front matter 中声明的分类”会共存重复项会被uniq!去重而 URL 中的:categories占位符会按照合并后的分类数组生成路径可参考 lib/jekyll/url.rb 中:categories占位符的模板定义。4.4 行为验证来自仓库的 Cucumber 测试仓库中的行为测试 features/post_data.feature 精确刻画了这套规则例如目录即分类文章位于movies/_posts/2009-03-27-star-wars.markdown渲染{{ page.categories }}输出movies输出文件为_site/movies/2009/03/27/star-wars.html目录 front matter 分类共存目录为movies、front matter 中category: film则page.categories为movies输出路径为_site/movies/film/2009/03/27/star-wars.html多分类合并categories: [film, scifi]时输出路径为_site/movies/film/scifi/2009/03/27/star-wars.html去重目录为movies、front matter 中category: movies时movies只出现一次。测试源码目录 test/fixtures/source/_posts/ 中还保留了es/子目录等历史用例可对照阅读。4.5 实操示例在站点中利用路径分类组织多语言或专题内容_posts/ ├── 2024-01-01-hello.markdown # 无分类 ├── es/ │ └── 2024-01-02-hola.markdown # 分类: es └── movies/ └── 2024-01-03-star-wars.markdown # 分类: movies配合 permalink 配置# _config.yml permalink: /:categories/:year/:month/:day/:title:output_ext构建后es/下的文章 URL 为/es/2024/01/02/hola.htmlmovies/下的文章 URL 为/movies/2024/01/03/star-wars.html根部文章保持默认路径。这样无需在 front matter 中重复书写分类目录结构即分类维护成本更低也利于 SEO 路径语义化。五、其他随版本修复的变更除三项核心更新外2.2.0 还包含若干附带修复见 History.markdown移除了Jekyll::Tags::IncludeTag中多余的#blank?方法#2625属于代码清理重构了第三方库的错误处理与 require 方式#2591为分类功能补充了更多测试#2584站点构建接入 html-proofer 校验#2605并修复了该机制自身的问题#2608。这些改动共同提升了 2.2.0 的质量基线其中“布局缺失告警”与“路径分类”两项至今仍是 Jekyll 的默认行为持续发挥作用。六、小结Jekyll 2.2.0 的三项更新分别落在可观测性、安全性与数据建模三个方向更新项类型今天的落点布局缺失告警可观测性lib/jekyll/renderer.rb 中validate_layout仍会输出 Build WarningPygments 选项安全模式白名单安全性高亮选项统一由 lib/jekyll/tags/highlight.rb 语法解析Pygments 已回退到 Rouge_posts路径分类数据建模lib/jekyll/document.rb 的categories_from_path行为由 features/post_data.feature 固化如果你正在排查“布局没生效但构建成功”的隐性故障、需要在受限环境下安全使用代码高亮或想用目录结构代替 front matter 维护文章分类这三项能力在今天依然是 Jekyll 工作流中的实用工具。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Jekyll 2.2.0 版本解析：布局缺失告警、安全模式高亮白名单与文章路径分类支持
Jekyll 2.2.0 版本解析布局缺失告警、安全模式高亮白名单与文章路径分类支持【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyllJekyll 2.2.0 是 2014 年 7 月发布的一个小版本更新聚焦于构建流程的健壮性与安全模式safe mode下代码高亮的可用性。本篇文章以 官方发布公告 为骨架结合当前仓库中的 History.markdown 变更记录与 lib/ 源码实现深入讲解“布局缺失告警”“Pygments 选项安全白名单”与“_posts路径分类”三项核心更新并给出可直接实践的配置与验证方式。读完本文你将理解这三项改动的触发条件、底层实现原理及在站点构建中的实际影响。一、发布背景与版本定位Jekyll 2.2.0 于 2014-07-29 发布由维护者 parkr 撰写发布公告。它是一个小版本minor功能更新不涉及破坏性变更主要包括三项关键更新在页面或文章的 front matter 中指定一个不存在的 layout 时构建过程将输出警告warning安全模式safe mode下Pygments 的部分选项被纳入白名单允许继续使用文章posts所在路径中的目录结构现在会被正确识别为分类categories即_posts下的子文件夹开始正常工作。发布公告同时指向完整的变更列表历史页面 中对应v2.2.0一节。在当前仓库的 History.markdown 中可以找到与公告一一对应的完整条目Minor EnhancementsThrow a warning if the specified layout does not exist (#2620)、Whitelist Pygments options in safe mode (#2642)Bug FixesRemove unnecessary Jekyll::Tags::IncludeTag#blank? method (#2625)、Categories in the path are ignored (#2633)以及若干开发与站点维护性修复如用 html-proofer 校验站点、更新第三方插件列表等。二、核心更新一缺失布局告警2.1 改动内容在此之前如果某个页面或文章的 front matter 里写了layout: my-layout而_layouts/目录中并不存在该布局文件Jekyll 会静默忽略并直接渲染页面正文用户很难察觉布局配置写错了。2.2.0 起构建过程会在这种情况下输出一条构建警告。2.2 当前源码实现这一行为延续至今实现在 lib/jekyll/renderer.rb。Renderer#place_in_layouts先从文档数据中取出 layout 名称并调用validate_layout校验def place_in_layouts(content, payload, info) output content.dup layout layouts[document.data[layout].to_s] validate_layout(layout) # ... 循环渲染 layout 链 end # Checks if the layout specified in the document actually exists def validate_layout(layout) return unless invalid_layout?(layout) Jekyll.logger.warn Build Warning:, Layout #{document.data[layout]} requested \ in #{document.relative_path} does not exist. end从源码可以看出两个细节告警消息会明确包含文档的相对路径document.relative_path方便快速定位是哪个文件写错了 layout校验发生在渲染链路入口place_in_layouts也就是说无论 layout 缺失与否页面内容仍会被渲染输出告警不会中断构建这与 Jekyll 一贯“尽量完成构建、同时把问题暴露给用户”的设计一致。2.3 布局的加载机制要理解“layout 不存在”判定需要看布局如何被读取。布局由 lib/jekyll/readers/layout_reader.rb 统一扫描它遍历layouts_dir默认_layouts以及主题theme的布局目录用layout_name去掉扩展名作为键存入layouts哈希def read layout_entries.each do |layout_file| layouts[layout_name(layout_file)] \ Layout.new(site, layout_directory, layout_file) end theme_layout_entries.each do |layout_file| layouts[layout_name(layout_file)] || \ Layout.new(site, theme_layout_directory, layout_file) end layouts end def layout_name(file) file.split(.)[0..-2].join(.) end因此layout: default对应的查找键是default它匹配_layouts/default.html或default.md等任意扩展名的文件。当 front matter 中的 layout 名称与任何一个已加载布局的键都不匹配时就会触发 2.2.0 引入的告警。2.4 实操验证以一个极简示例复现该告警在站点根目录创建_layouts/目录放入一个simple.html布局创建一篇文章_posts/2024-01-01-hello.mdfront matter 写为layout: no_such_layout执行构建jekyll build构建仍会成功完成但终端会输出类似如下的警告Build Warning: Layout no_such_layout requested in _posts/2024-01-01-hello.md does not exist.这对于排查“页面样式/结构没生效但构建又没报错”的问题非常实用。配套的回归测试覆盖于 test/test_renderer.rb 等渲染相关测试中可作进一步参考。三、核心更新二安全模式下 Pygments 选项白名单3.1 改动内容Jekyll 的--safe安全模式用于在不可信环境如 GitHub Pages 或插件沙箱中禁用自定义插件与部分危险特性。2.2.0 之前安全模式会对代码高亮标签{% highlight %}的可用选项做严格限制本次更新将部分 Pygments 选项纳入白名单使安全模式下的代码高亮仍然可用且可控PR #2642。3.2 代码高亮标签的现状需要说明的是当前仓库的 Jekyll 版本已默认使用 Rouge 作为高亮器Pygments 渲染路径已降级为回退并提示改用 Rouge。在 lib/jekyll/tags/highlight.rb 中def render(context) # ... output case context.registers[:site].highlighter when rouge render_rouge(code) when pygments render_pygments(code, context) else render_codehighlighter(code) end # ... end def render_pygments(code, _context) Jekyll.logger.warn Warning:, Highlight Tag no longer supports rendering with Pygments. Jekyll.logger.warn , Using the default highlighter, Rouge, instead. render_rouge(code) end也就是说即使在配置中指定highlighter: pygments当前版本也会输出警告并回退到 Rouge。2.2.0 时代的 Pygments 白名单属于当时的历史行为其精神延续到今天的 Rouge 实现中highlight标签的选项解析parse_options会按照固定的语法规则提取linenos、mark_lines3 4 5等选项未在白名单/语法内的写法会直接抛出 SyntaxError 而非悄悄执行SYNTAX %r!^([a-zA-Z0-9.#_-])((\s\w((\w|([0-9]\s)*[0-9]))?)*)$!.freeze def initialize(tag_name, markup, tokens) super if markup.strip ~ SYNTAX lang Regexp.last_match(1).downcase highlight_options parse_options(Regexp.last_match(2)) else raise SyntaxError, ~MSG Syntax Error in tag highlight while parsing the following markup: ... Valid syntax: highlight lang [linenos] [mark_lines3 4 5] MSG end end3.3 安全模式下的现代实践在今天的 Jekyll 中安全模式下使用代码高亮的推荐方式依赖默认高亮器Rougehighlighter: rouge它原生支持白名单化的语言与选项解析在_config.yml中通过markdown/kramdown.syntax_highlighter等相关配置声明高亮器使用标准语法书写代码块{% highlight ruby linenos %} def hello puts world end {% endhighlight %}linenos会启用行号内部归一化为inline行号形式mark_lines3 4 5可高亮指定行。这些选项的解析逻辑均可追溯到 lib/jekyll/tags/highlight.rb并有 test/test_tag_highlight.rb 提供行为保证。四、核心更新三_posts路径中的分类识别4.1 改动内容2.2.0 修复了一个长期存在的 bug#2633以前_posts下的子文件夹如_posts/es/2014-01-01-x.markdown中的目录名会被忽略从 2.2.0 开始这些目录名会被正确提取为该文章的 categories。4.2 当前源码实现该逻辑今天位于 lib/jekyll/document.rb。Document#populate_categories会合并三类来源从文件路径中提取的目录名categories_from_pathfront matter 中的category字段转为数组front matter 中的categories字段数组或逗号分隔。路径提取的核心是categories_from_path# Add superdirectories of the special_dir to categories. # In the case of es/_posts, es is added as a category. # In the case of _posts/es, es is NOT added as a category. def categories_from_path(special_dir) if relative_path.start_with?(special_dir) superdirs [] else superdirs relative_path.sub(Document.superdirs_regex(special_dir), ) superdirs superdirs.split(File::SEPARATOR) superdirs.reject! { |c| c.empty? || c special_dir || c basename } end merge_data!({ categories superdirs }, :source file path) end注意注释中特别强调的两个方向性差异es/_posts/..._posts前有目录→ 该目录es会被加入 categories_posts/es/..._posts内建子目录→ 该目录es不会被加入 categories这是刻意设计避免与默认:categories占位符产生歧义。4.3 与 front matter 分类的合并规则populate_categories会把路径分类与 front matter 分类合并并去重def populate_categories categories Array(data[categories]) Utils.pluralized_array_from_hash( data, category, categories ) categories.map!(:to_s) categories.flatten! categories.uniq! merge_data!({ categories categories }) end因此“目录名 front matter 中声明的分类”会共存重复项会被uniq!去重而 URL 中的:categories占位符会按照合并后的分类数组生成路径可参考 lib/jekyll/url.rb 中:categories占位符的模板定义。4.4 行为验证来自仓库的 Cucumber 测试仓库中的行为测试 features/post_data.feature 精确刻画了这套规则例如目录即分类文章位于movies/_posts/2009-03-27-star-wars.markdown渲染{{ page.categories }}输出movies输出文件为_site/movies/2009/03/27/star-wars.html目录 front matter 分类共存目录为movies、front matter 中category: film则page.categories为movies输出路径为_site/movies/film/2009/03/27/star-wars.html多分类合并categories: [film, scifi]时输出路径为_site/movies/film/scifi/2009/03/27/star-wars.html去重目录为movies、front matter 中category: movies时movies只出现一次。测试源码目录 test/fixtures/source/_posts/ 中还保留了es/子目录等历史用例可对照阅读。4.5 实操示例在站点中利用路径分类组织多语言或专题内容_posts/ ├── 2024-01-01-hello.markdown # 无分类 ├── es/ │ └── 2024-01-02-hola.markdown # 分类: es └── movies/ └── 2024-01-03-star-wars.markdown # 分类: movies配合 permalink 配置# _config.yml permalink: /:categories/:year/:month/:day/:title:output_ext构建后es/下的文章 URL 为/es/2024/01/02/hola.htmlmovies/下的文章 URL 为/movies/2024/01/03/star-wars.html根部文章保持默认路径。这样无需在 front matter 中重复书写分类目录结构即分类维护成本更低也利于 SEO 路径语义化。五、其他随版本修复的变更除三项核心更新外2.2.0 还包含若干附带修复见 History.markdown移除了Jekyll::Tags::IncludeTag中多余的#blank?方法#2625属于代码清理重构了第三方库的错误处理与 require 方式#2591为分类功能补充了更多测试#2584站点构建接入 html-proofer 校验#2605并修复了该机制自身的问题#2608。这些改动共同提升了 2.2.0 的质量基线其中“布局缺失告警”与“路径分类”两项至今仍是 Jekyll 的默认行为持续发挥作用。六、小结Jekyll 2.2.0 的三项更新分别落在可观测性、安全性与数据建模三个方向更新项类型今天的落点布局缺失告警可观测性lib/jekyll/renderer.rb 中validate_layout仍会输出 Build WarningPygments 选项安全模式白名单安全性高亮选项统一由 lib/jekyll/tags/highlight.rb 语法解析Pygments 已回退到 Rouge_posts路径分类数据建模lib/jekyll/document.rb 的categories_from_path行为由 features/post_data.feature 固化如果你正在排查“布局没生效但构建成功”的隐性故障、需要在受限环境下安全使用代码高亮或想用目录结构代替 front matter 维护文章分类这三项能力在今天依然是 Jekyll 工作流中的实用工具。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考