Jekyll 分类大小写实战指南解析category: MixedCase的写入、保留与 URL 生成机制【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyllJekyll 是使用 Ruby 编写的博客感知型静态站点生成器分类categories与标签tags是它组织文章内容的两大核心维度。本文以 2014-07-05-mixed-case-category.markdown 这一真实测试夹具为线索深入讲解分类在 Front Matter 中的声明方式、大小写保留规则、目录式分类的来源以及分类值如何参与默认 URLpermalink模板的生成。读完本文你将掌握如何正确声明与查询混合大小写分类并理解为什么目录中的 MixedCase 与 Front Matter 中的 MixedCase 会走向不同的 URL。测试夹具概览一份只有七行的微型文章先看这份文档的完整内容--- layout: default title: Mixed Case Category in YAML category: MixedCase --- Best *post* ever这份位于test/source/_posts/下的夹具由三部分组成Front Matter 数据layout: default声明使用测试源目录中的默认布局test/source/_layouts/default.htmltitle提供文章标题category: MixedCase声明文章属于名称为MixedCase的分类。正文内容Best *post* ever是一行 Markdown其中的*post*会被渲染为斜体。文件命名2014-07-05-mixed-case-category.markdown遵循 Jekyll 文章的标准命名规范——YYYY-MM-DD-slug.ext由文件名即可解析出发布日期 2014 年 7 月 5 日。这个夹具在仓库中的作用是验证一个具体行为当分类名包含大写字母MixedCase时Jekyll 会原样保留其大小写并将其作为站点级分类数据的一部分暴露给模板。下文将结合源码逐步拆解这一行为。分类的两大来源Front Matter 声明与目录结构在 Jekyll 中一篇文章的分类值可以来自两个互不排斥的地方最终会被合并到同一个categories数据字段中。理解这一点是掌握分类机制的基础。来源一Front Matter 中的category/categoriesDocument#populate_categorieslib/jekyll/document.rb是处理声明的核心逻辑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这段代码的关键行为单复数同源Utils.pluralized_array_from_hash(data, category, categories)允许用户既写category: MixedCase单数也写categories: [A, B]复数两者会被统一归一化进categories数组字符串化与扁平化无论声明为字符串还是数组都会to_s并flatten!成字符串数组去重uniq!保证同一分类值不会重复出现大小写原样保留整个过程没有任何downcase或upcase调用——这正是本文主题的根源。对比另一份测试夹具 2013-12-20-properties.text它以categories: foo bar baz MixedCase的形式声明了包含混合大小写分类的数组两份夹具共同验证了单数与复数写法下大小写均被保留。来源二文章所在目录路径除了显式声明Jekyll 还会把文章在_posts下的子目录名自动作为分类。Document#categories_from_pathlib/jekyll/document.rb实现了这一逻辑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/时es会被加入分类文章位于_posts/es/时es不会被加入分类。分类来源的合并发生在Document#merge_categories!lib/jekyll/document.rb若 Front Matter 中的categories是字符串会先split成数组若文件路径分类已是数组则用data[categories] | other[categories]做数组并集兼顾去重与顺序。整个过程同样不改写大小写。站点级聚合site.categories的构建与双键共存现象单篇文章的分类最终要汇总到站点层面供模板遍历使用。这一工作由Site#post_attr_hashlib/jekyll/site.rb完成def post_attr_hash(post_attr) post_attr_hash[post_attr] || begin hash Hash.new { |h, key| h[key] [] } posts.docs.each do |p| p.data[post_attr].each { |t| hash[t] p } end hash.each_value { |posts| posts.sort!.reverse! } hash end end def categories post_attr_hash(categories) end该方法以原始值作为哈希键构建{ 分类名 文章数组 }映射Hash.new { |h, key| h[key] [] }保证每个键首次出现即获得空数组随后文章被追加进去最后每个分类下的文章按日期倒序排列。Site#categories与Site#tagslib/jekyll/site.rb共用该实现Site#site_payload则将其包装进Drops::UnifiedPayloadDroplib/jekyll/site.rb最终通过 lib/jekyll/drops/site_drop.rb 的delegate_methods :time, :pages, :static_files, :tags, :categories暴露为模板中的site.categories。由此产生一个重要的实践结论——大小写敏感的分类名会作为两个独立键共存。test/test_site.rb的deploy payload用例test/test_site.rb直接断言了这一点categories %w( 2013 bar baz category foo z_category MixedCase Mixedcase publish_test win ).sort assert_equal categories, site.categories.keys.sort注意其中同时存在MixedCase与Mixedcase两个键前者来自本文夹具的 Front Matter 声明以及properties.text的数组声明后者来自目录路径生成的分类。测试源目录中_posts/2013-03-19-not-a-post/、z_category/等子目录的存在也让2013、z_category等目录名进入同一键集合。分类值如何进入 URL大小写在 URL 中会被降级分类不仅用于聚合展示还深度参与 URL 生成。Jekyll 内置的默认 permalink 模板lib/jekyll/configuration.rb都以/:categories/开头:none /:categories/:title:output_ext, :date /:categories/:year/:month/:day/:title:output_ext, :ordinal /:categories/:year/:y_day/:title:output_ext, :pretty /:categories/:year/:month/:day/:title/, :weekdate /:categories/:year/W:week/:short_day/:title:output_ext,也就是说分类名会被拼进最终 URL 路径。而 URL 中分类段的生成依赖Jekyll::Utils.slugifylib/jekyll/utils.rbdef slugify(string, mode: nil, cased: false) mode || default return nil if string.nil? unless SLUGIFY_MODES.include?(mode) return cased ? string : string.downcase end ... slug.downcase! unless cased slug endslugify在非cased模式下会执行slug.downcase!将大写字母转成小写。因此Front Matter 中的category: MixedCase在site.categories中保留为MixedCase键但在默认 URL 中会以小写形式呈现对应目录名或 slug 化后的小写段。这一不对称行为由 test/test_excerpt.rb 的断言精确印证assert_equal Post Excerpt with Layout, excerpt.to_liquid[title] url /bar/baz/z_category/mixedcase/2013/07/22/post-excerpt-with-layout.html assert_equal url, excerpt.to_liquid[url] assert_equal %w(bar baz z_category MixedCase), excerpt.to_liquid[categories]同一篇2013-07-22-post-excerpt-with-layout.markdown文章其 Front Matter 中声明了categories: [bar, baz, MixedCase]test/source/_posts/2013-07-22-post-excerpt-with-layout.markdownto_liquid[categories]输出%w(bar baz z_category MixedCase)——分类数据保留原始大小写to_liquid[url]输出/bar/baz/z_category/mixedcase/...——URL 中的分类段全部为小写。从夹具到实战四步写出可验证的分类文章综合以上机制要在自己的 Jekyll 站点中声明并使用混合大小写分类可以按以下流程操作仓库测试源目录即示范了全部要素声明分类在_posts/YYYY-MM-DD-slug.markdown的 Front Matter 中写入单数或复数形式例如category: MixedCase或categories: [Foo, bar, MixedCase]构建站点运行jekyll build或开发时jekyll serve。Document#read_post_data会在读取文章时依次调用populate_title、populate_categories、populate_tagslib/jekyll/document.rb完成分类的规范化与合并模板中遍历在布局或页面中使用site.categories按分类聚合文章例如{% for category in site.categories %}{{ category | first }}注意键的大小写敏感性与声明时完全一致验证输出查看生成的_site目录观察文章实际 URL 中分类段的小写形态与site.categories键的大小写进行对照。如需验证分类聚合的最终产物可运行仓库的单元测试test/test_site.rb的deploy payload用例构建整个测试站点并断言site.categories.keys.sort这正是对本文所述大小写行为的端到端回归测试。总结本文围绕 2014-07-05-mixed-case-category.markdown 这一测试夹具梳理了 Jekyll 分类机制的完整链路环节行为源码依据Front Matter 声明解析单复数归一、字符串化、扁平化、去重大小写原样保留lib/jekyll/document.rb目录路径分类_posts上层目录加入分类路径分类与声明分类做并集lib/jekyll/document.rb站点聚合以原始值作键构建{ 分类名 文章数组 }MixedCase与Mixedcase可作为独立键共存lib/jekyll/site.rbURL 生成默认 permalink 模板含/:categories/经slugify后分类段降为小写lib/jekyll/configuration.rb、lib/jekyll/utils.rb核心结论分类数据本身是大小写敏感的并保留原样而 URL 中的分类段默认会小写化。在设计分类体系时建议全站统一大小写风格避免同一语义分类因大小写差异在site.categories中分裂为多个键同时也要意识到 URL 与数据两套表现形式的差异才能让分类导航、归档页面与永久链接保持一致。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考