Jekyll 2.1.0 版本深度解读Collections 配置补全、_data 目录扩展与 serve 工作流改进【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyllJekyll 2.1.02014 年 6 月 28 日发布是 Jekyll 由“个人博客生成器”迈向“通用静态站点生成器”过程中的一个关键版本它补全了 Collections 的前端配置能力、扩展了_data目录的数据格式与目录结构、增强了highlight代码高亮标签并为本地开发工作流引入了--skip_initial_build旗标。本文以官方发布说明docs/_posts/2014-06-28-jekyll-turns-21-i-mean-2-1-0.markdown为核心骨架结合当前仓库的源码实现与测试用例逐项还原这些特性的设计意图、配置方法与底层原理帮助读者既理解历史版本的设计脉络也能在今天的 Jekyll 中正确使用这些沿袭下来的能力。一、版本背景从 2.0 到 2.1一次里程碑式的功能补全发布说明的标题玩了一个双关——Jekyll Turns 21既指 Jekyll 在版本号上“长大成人”2.1.0 恰好是 21 的十进制形态美国法定饮酒年龄也是 21 岁也暗示这个版本“该承担更多责任了”。事实上2.1.0 正是在 2.0 全面引入 Collections 之后对这套新机制进行的第一次系统性补全。该版本的完整变更记录位于仓库根目录的 History.markdown## 2.1.0 / 2014-06-28一节而发布说明中提到的完整 changelog 页面对应文档站点的 docs/_docs/history.md。官方发布说明列出了本次版本的核心亮点而完整 changelog 则记录了 25 项 Minor Enhancements、21 项 Bug Fixes、3 项开发修复与 23 项站点改进。据发布说明所述本次发布共收到37 位贡献者的代码提交包括 Parker Moore发布说明作者、Ben Balter、Alfred Xing、Jordon Bedwell 等社区活跃成员这是 Jekyll 早期社区协作规模的一次集中体现。二、基础依赖升级Liquid 2.6.1 与 pygments.rb 0.6.0发布说明列出的第一项更新是将 Liquid 模板引擎升级到2.6.1PR #2495这为模板渲染层的稳定性和新语法提供了基础保障。同期语法高亮依赖pygments.rb 升级到 0.6.0PR #2504并新增了对hl_lines行高亮选项的支持详见第五节。需要注意的是这两个依赖在今天的 Jekyll 中已发生重要变化。当前仓库的 lib/jekyll/tags/highlight.rb 中render_pygments方法会直接输出告警并回退到默认的 Rouge 高亮器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也就是说从源码结构看Pygments 渲染路径已被明确废弃Rouge 成为默认且唯一完整支持的高亮后端。这提醒读者在阅读 2.1.0 时代的文档时需将“Pygments”相关配置视为历史形态当前项目以 Rouge 为准。三、Collections 的配置能力补全Collections集合是 Jekyll 2.0 引入的通用内容组织机制而 2.1.0 为其补齐了两块关键配置能力front matter 默认值与专属 URL 模板。3.1 为 Collections 设置 Front Matter 默认值#2419在此之前front matter 默认值_config.yml中的defaults配置主要作用于 pages 与 posts2.1.0 将这一机制扩展到 collection 文档使同一集合内的所有文档可以共享统一的布局、元数据与字段默认值。当前实现位于 lib/jekyll/frontmatter_defaults.rb其匹配逻辑由scope中的type与path共同决定scope.type限定文档类型。当前仓库还支持pages、posts、drafts并提供了page/post/draft旧写法的自动迁移见 frontmatter_defaults.rb 的update_deprecated_types对 collections直接使用集合标签名label作为 type。scope.path限定路径范围支持目录前缀与 glob 通配*具体逻辑见 applies_path?。优先级规则has_precedence?frontmatter_defaults.rb保证路径更具体、声明了 type 的默认值集合拥有更高优先级all方法通过Utils.deep_merge_hashes逐层深合并各集合的values。典型配置示例_config.ymldefaults: - scope: path: # 全局生效 values: layout: default - scope: path: _staff # 集合目录 type: staff # 集合标签 values: layout: staff role: member有了这层默认值后集合内每个文档只需声明自身特有字段公共字段由默认值注入——这与页面、文章的默认值行为完全一致是“DRYDont Repeat Yourself”理念在集合层面的落地。3.2 集合专属 URL 模板#24182.1.0 允许为每个集合单独指定 URL 模板permalink 模式。当前实现中Collection#url_template 会优先读取集合配置里的permalink字段缺省时使用/:collection/:path并附加站点的 permalink 后缀def url_template url_template || metadata.fetch(permalink) do Utils.add_permalink_suffix(/:collection/:path, site.permalink_style) end end在_config.yml中collections 既可以用列表形式声明也可以用 Hash 形式携带配置collections: staff: output: true # 决定文档是否被渲染为独立文件 permalink: /team/:name/ # 集合专属 URL 模板 faqs: output: trueoutput: true决定集合文档是否写入输出目录见 write?而permalink决定 URL 形态。这两项配置配合前文的 defaults构成了现代 Jekyll 中“集合即站点模块”的标准用法——例如本仓库文档站点的_docs、_tutorials目录在 docs/_config.yml 中即以此方式组织。四、_data目录增强JSON 支持与子目录#2369 / #23952.1.0 对站点的数据文件机制做了两项扩展支持.json文件#2369此前_data仅支持 YAML现在 JSON 也成为一等公民允许_data内使用子目录#2395此前所有数据文件必须平铺现在可以通过子目录进行结构化组织。这两项能力在今天的DataReader中依然完整保留。核心递归逻辑位于 lib/jekyll/readers/data_reader.rbdef read_data_to(dir, data) return unless File.directory?(dir) !entry_filter.symlink?(dir) entries Dir.chdir(dir) do Dir[*.{yaml,yml,json,csv,tsv}] Dir[*].select { |fn| File.directory?(fn) } end entries.each do |entry| path in_source_dir.call(dir, entry) next if entry_filter.symlink?(path) if File.directory?(path) read_data_to(path, data[sanitize_filename(entry)] {}) else key sanitize_filename(File.basename(entry, .*)) data[key] read_data_file(path) end end end关键行为可以从源码中确认格式当前支持yaml、yml、json、csv、tsv五种扩展名read_data_file对非 CSV/TSV 文件统一走SafeYAML.load_file。递归遇到子目录时递归调用自身并将该目录映射为数据哈希中的一个嵌套键。键名清洗sanitize_filenamedata_reader.rb会移除文件名中的非\w/空白字符并将连续空白替换为下划线因此文件名需避免使用特殊字符。仓库测试 fixture 为这两项特性提供了直接证据test/source/_data/下既有members.jsonJSON 支持也有categories/、categories.01/等子目录子目录支持对应测试位于 test/test_data_reader.rb。使用效果示例若_data目录结构为_data/ products.yml categories/ tools.yml services.yml则模板中可通过site.data.categories.tools、site.data.products直接访问嵌套数据无需再手工拼装。五、highlight标签的行高亮选项#2532发布说明中的hl_lines为highlight标签引入了“仅高亮指定代码行”的能力这在展示 diff、重点讲解某段逻辑时非常实用。2.1.0 时代的使用方式是{% highlight ruby hl_lines3 4 %} def hello # 普通行 puts highlighted # 第 3 行 # 第 4 行也会被高亮 end {% endhighlight %}在今天Jekyll 4.x/5.x 世代的源码中该选项更名为mark_lines但机制一脉相承。lib/jekyll/tags/highlight.rb 中的line_highlighter_formatter将mark_lines解析为行号数组并交由 Rouge 的HTMLLineHighlighter渲染def line_highlighter_formatter(formatter) Rouge::Formatters::HTMLLineHighlighter.new( formatter, :highlight_lines mark_lines ) end当前标签的合法语法为见 highlight.rb 的错误提示highlight lang [linenos] [mark_lines3 4 5]其中linenos控制是否显示行号默认inline行内模式table模式走HTMLTable分栏渲染见 table_formatter。若读者在旧文档或第三方博客中看到hl_lines应将其替换为今天的mark_lines对应测试可参考 test/test_tag_highlight.rb。六、Post 分类的三路合并#2373在 2.1.0 之前文章的分类categories来源彼此割裂本次修复#2373统一了分类的合并逻辑使目录结构、front matter、默认值三处声明的分类最终合并为一套去重后的完整列表。当前实现位于 lib/jekyll/document.rbdef 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合并顺序可以从Document的读取流程推断先由文件系统路径注入分类——文章所在目录的上级目录会作为分类写入merge_categories!及superdirs逻辑见 document.rb再由 front matter 中的categories或单数category字段追加最后由 front matter 默认值为未声明分类的文章补全。三者经flatten展平、uniq去重后写入文档数据。这意味着即便某篇文章完全没有在 front matter 中写categories只要它位于_posts下的分类子目录Jekyll 也会自动为其归类——这是“目录即分类”这一 Jekyll 传统约定的代码级保证。七、jekyll serve新旗标--skip_initial_build#2477发布说明中最具开发工作流价值的新增项是jekyll serve的--skip_initial_build旗标PR #2477。其语义非常明确跳过服务启动前的首次全量构建。对于配合--watch使用的场景例如站点已构建好、只想快速启动本地预览这能显著缩短启动等待时间。该选项在当前仓库中依然存在。服务端注册于 lib/jekyll/commands/serve.rbskip_initial_build [skip_initial_build, --skip-initial-build, Skips the initial site build which occurs before \ the server is started.,],而真正消费该选项的是构建流程 lib/jekyll/commands/build.rbif options.fetch(skip_initial_build, false) Jekyll.logger.warn Build Warning:, Skipping the initial build. This may result in an out-of-date site. else build(site, options) end两点值得说明命名演进2.1.0 发布说明中写作--skip_initial_build下划线今日的 CLI 旗标为--skip-initial-build连字符内部选项键仍是skip_initial_build两者在配置文件中均可识别。正确用法该旗标适合“站点已构建、只差预览”的场合。源码特意给出了警告——跳过初始构建可能提供过期的站点内容若目标目录为空或不完整仍建议保留默认的初始构建。典型命令jekyll serve --skip-initial-build --watch # 或 jekyll serve --skip-initial-build -w八、2.1.0 的其他增强与关键 Bug 修复发布说明末尾以“a bajillion bug fixes and site updates!”概括了大量细节改进完整清单见 History.markdown。以下是其中对后续版本影响较大、且在今日代码中可溯源的条目8.1 值得关注的 EnhancementsJekyll.env与模板变量jekyll.environment#2417环境感知从此成为一等公民JEKYLL_ENVproduction jekyll build的工作方式由此确立参见 docs/_docs/configuration/environments.md。支持_config.yaml或_config.yml且.yml优先#2406扩展了配置文件名兼容性。可配置、可替换的 Logger#2444日志组件开始走向插件化对应今天的 lib/jekyll/log_adapter.rb。分拆 gem 的序幕分页生成器拆为jekyll-paginate#2455、gist标签拆为独立 gem#2469、--watch能力也进行了独立化实验#2550。这是 Jekyll 核心逐步瘦身、功能外移的起点。listen 依赖放宽到2.7.6 x 3.0.0#2492为监听文件变化提供了更稳定的依赖区间。8.2 关键 Bug Fixesfront matter 默认值可设置 post 分类#2373与第六节的三路合并直接相关。front matter 默认值深度合并#2490嵌套结构的默认值不再互相覆盖见FrontmatterDefaults#all中的deep_merge_hashes。sort过滤器在存在nil值时仍能排序#2345。keep_files保留文件/目录的全部父目录#2458。UTF-8 转义与反转义#2420URL 编码统一按 UTF-8 处理。自动生成watch时忽略所有应忽略的文件#2459以及collections 文件名可含点、不把目录当文件读取#2552。九、从 2.1.0 到今天的演进脉络以 2.1.0 为坐标回看今天的仓库可以清晰归纳出几条演进主线2.1.0 时代今天本仓库说明hl_lineshighlight 标签mark_lines3 4 5选项更名机制保留highlight.rb--skip_initial_build旗标--skip-initial-buildCLI 命名规范化serve.rb_data支持 YAML/JSON扩展至 YAML/YML/JSON/CSV/TSV 且支持递归子目录能力持续扩展data_reader.rbPygments 0.6.0 高亮Rouge 为默认高亮器Pygments 路径输出弃用警告依赖换代highlight.rb集合 URL 模板 / 默认值机制原样保留并继续演进sort_by、order等排序能力见 collection.rb可以说2.1.0 奠定的“集合可配置、数据可结构化、构建流程可控制”三大方向至今仍是 Jekyll 的核心体验后续版本的工作大多是在这些地基上做扩展与打磨。十、延伸阅读如需继续深入本仓库验证本文结论可查阅以下资源2.1.0 完整变更记录History.markdown 与 docs/_docs/history.md官方发布说明原文docs/_posts/2014-06-28-jekyll-turns-21-i-mean-2-1-0.markdown功能实现源码data_reader.rb、frontmatter_defaults.rb、collection.rb、document.rb、highlight.rb、serve.rb、build.rb测试与数据 fixturetest/test_data_reader.rb、test/test_front_matter_defaults.rb、test/test_tag_highlight.rb、test/source/_data/当代使用文档docs/_docs/collections.md、docs/_docs/datafiles.md、docs/_docs/configuration.md、docs/_docs/usage.md【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考