Jekyll 版本历史解析从 v0.0.0 到 v4.4.1 的技术演进与 Changelog 生成机制【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll本文基于 Jekyll 官方仓库的 History 文档docs/_docs/history.md展开系统梳理 Jekyll 自 2008 年 10 月 v0.0.0 诞生至 2025 年 1 月 v4.4.1 的完整版本脉络逐版本解析 0.x/1.x/2.x/3.x/4.x 各阶段的核心技术里程碑Collections、增量重建、Hooks、磁盘缓存等并直接引用仓库中的 Rakefile 与 rake/site.rake 源码讲清这个 Changelog 页面是如何从 History.markdown 自动生成的帮助读者既能快速定位“某个特性/修复在哪个版本引入”也能理解 Jekyll 多版本并行维护的策略。History 文档是什么一份自动生成的 Changelogdocs/_docs/history.md 是 Jekyll 文档站的 History 页面其 front matter 中有这样一段自述--- title: History permalink: /docs/history/ note: This file is autogenerated. Edit /History.markdown instead. ---这说明了三个关键事实它不是手工维护的而是由构建文档站的 Rake 任务从仓库根目录的 History.markdown 转换生成因此仓库中的唯一“真相来源”是后者页面发布在/docs/history/固定地址下全文按“版本倒序”组织共约 4600 行从最新的## 4.4.1 / 2025-01-29一直追溯到## 0.0.0 / 2008-10-19文档末尾仅标注 “Birthday!”。每个版本条目内部按类别划分小节这些类别在整份文档中高度一致是阅读 Changelog 的基本坐标系类别含义Major Enhancements重大功能通常伴随主版本号提升Minor Enhancements功能增强次版本号提升时出现Bug Fixes缺陷修复Development Fixes仅影响开发流程CI、测试、RuboCop、脚本等的变更Security Fixes安全修复Documentation文档站点/文档内容的变更Site Enhancements文档站点本身的前端改进Forward Ports / Meta从旧稳定分支前向合并的变更、纯流程性说明每条变更末尾都附带 PR/Issue 编号如(#9762)在文档站渲染后会被链接到上游仓库的对应 issue这是定位实现细节的最短路径。版本时间线各主版本的技术里程碑0.x2008–2012从首次发布到插件系统v0.1.0 / 2008-11-05首次发布。当时 Jekyll 还很简单——转换 Textile 书写的文章、处理普通站点页面、复制二进制文件。v0.3.0 / 2010-08-24加入--server选项用 WEBrick 在输出目录上起本地服务器奠定了jekyll serve的基础。v0.5.1 / 2009-05-06引入“Permalink templating system”permalink 模板系统、上一篇/下一篇导航以及配置中的exclude选项——permalink 占位符机制至今仍是 Jekyll URL 生成的核心。v0.6.0 / 2010-06-23建立正式的插件系统Converter/Generator 分类和 safe mode允许加载“不安全”的第三方转换器这一版本也确立了 Maruku 为默认 Markdown 处理器的依赖策略其余处理器按需懒加载。v0.11.0 / 2011-07-10加入命令行导入器WordPress、Tumblr、Posterous 等和 Redcarpet 支持。v0.12.0 / 2012-12-22加入include文件显式包含选项、post_urlLiquid 标签并用 pygments.rb 替换 Albino。1.x2013CLI 子命令化与数据目录v1.0.0 / 2013-05-06命令体系重构为子命令build/serve/migrate新增jekyll new一键生成站点脚手架模板位于 lib/site_template支持_drafts草稿渲染导入器被剥离到独立的 jekyll-import 子 gem——“核心精简、扩展外置”的路线在此成型。v1.2.0 / 2013-09-06加入jekyll doctor命令用于检查站点已知兼容性问题与 URL 冲突命令实现在 lib/jekyll/commands/doctor.rb。v1.3.0 / 2013-11-04三项重要能力落地——_data目录数据文件YAML、include标签支持变量传参、以及基于 gem 的插件管理后来演变为gems/plugins配置键。v1.4.0 / 2013-12-07支持 TOML 配置文件自动加载_config.toml仓库测试夹具 test/source/_config.dev.toml 即为其用例。2.x2014–2016Collections 与依赖生态现代化v2.0.0 / 2014-05-06这是 Jekyll 历史上最重要的版本之一新增Collections功能除posts外可定义任意内容集合用mercenary替换 commander 作为命令行解析器jekyll.gemspec 中至今依赖mercenary ~ 0.3移除 Ruby 1.8.x 支持引入 Rouge 语法高亮、Sass 与 CoffeeScript 支持默认 Markdown 处理器由 Maruku 换成 Kramdown引入 front matter defaults见 lib/jekyll/frontmatter_defaults.rb废弃relative_permalinks排除规则同时支持前缀与fnmatch?通配。v2.1.0 / 2014-06-28_data支持 JSON 文件与子目录暴露Jekyll.env与 Liquid 变量jekyll.environment分页逻辑从核心抽出为独立的 jekyll-paginate gem。v2.2.0 / 2016-07-26引入gem-based themes以 gem 形式分发的主题主题 gem 模板见 lib/theme_template并新增linkLiquid 标签与where_exp表达式过滤过滤器。v2.4.0 / 2014-09-09include_relative标签、serve自动开启 watch、CoffeeScript 文件中可渲染 Liquid、_data支持 CSV、新增slugify过滤器。v2.5.0 / 2014-11-06新增JEKYLL_LOG_LEVEL环境变量控制日志级别WEBrick 支持目录 Fancy Indexing。3.x2015–2018增量重建、Hooks 与性能优化v3.0.0 / 2015-10-26第二个“里程碑级”版本Incremental regeneration增量重建基于.jekyll-metadata文件只重新生成变更过的文档--incremental开关核心实现在 lib/jekyll/regenerator.rbHooks新增的一类插件允许在构建生命周期各阶段挂接逻辑lib/jekyll/hooks.rbLiquid profiler测量模板渲染耗时升级 Liquid 3.0site.posts从 Array 变为 Collection 对象开始支持 JRuby移除 Ruby 1.9.3日落移除Maruku输出文件始终带扩展名永久链接改进并新增时间占位符。v3.2.0 / 2016-07-26jekyll new-theme命令、normalize_whitespace与to_integer过滤器、可通过配置开关启用/放宽 Liquid 严格解析。v3.3.0 / 2016-10-06加入absolute_url与relative_url过滤器今天 URL 生成的主力工具实现见 lib/jekyll/filters/url_filters.rbjekyll new后自动执行bundle install。v3.5.0 / 2017-06-18_data支持 TSV升级 Liquid v4用plugins配置键替换gems新增strict_front_matter让构建可在 front matter 语法错误时失败。v3.7.0 / 2018-01-02jekyll serve内置LiveReload配合 em-websocketgemspec 中em-websocket ~ 0.5依赖即来源于此collections_dir配置允许把所有集合目录收敛到一个子目录下升级 Rouge 3。v3.8.x以性能为主线的维护版本官方在 v3.8.0 中明确记录了“两个针对大型站点的重大性能改进”、where过滤器内置缓存等。4.x2019–至今磁盘缓存与遗留依赖清理v4.0.0 / 2019-08-19第三个里程碑版本主线是“减负”移除 Ruby 2.1/2.2/2.3 支持移除 Pygments 高亮、Redcarpet、rdiscount 支持Kramdown 成为唯一的内建 Markdown 路径新增Jekyll::Cache类处理磁盘缓存缓存已转换的 Markdown 与解析后的 Liquid 模板并新增cache_dir配置实现见 lib/jekyll/cache.rbKramdown 升级到 2.xjekyll-sass-converter 升级到 2.x改用 libsass/sassc 并提供 sourcemap。v4.1.0 / 2020-05-27新增--profile选项对构建各阶段计时输出表格lib/jekyll/profiler.rb新增find/find_where等过滤器优化where first链式调用number_of_words过滤器适配 CJK 字符。v4.2.0 / 2020-12-14新增:post_convert钩子让插件在布局渲染前修改 HTML 内容在命令行层面警告 permalink 冲突并包含一批专门的“Optimization Fixes”缓存Jekyll.sanitized_path、memoize 各类中间结果。v4.3.0 / 2022-10-20将webrick显式列为运行时依赖gemspec 中webrick ~ 1.7引入themedrop 向 Liquid 暴露主题 gem 元信息lib/jekyll/drops/theme_drop.rb支持 jekyll-sass-converter 3.xDart Sass修复 CVE-2021-28834。v4.3.1 / 2022-10-26仅隔 6 天发布的补丁版本回退了“数据文件变更时增量重建”的行为该回退在后续 4.3.x 中一直保留是理解 4.3 增量构建边界的关键记录。v4.4.0 / 2025-01-27highlight标签支持通过 Liquid 标记特定高亮行mark_lines最低 Ruby 版本提升到 2.7把csv、json、base64显式加入运行时依赖与 gemspec 中csv ~ 3.0、json ~ 2.6、base64 ~ 0.2一一对应livereload_port开始接受来自站点配置的取值。v4.4.1 / 2025-01-29当前 master 分支的稳定版本lib/jekyll/version.rb 中VERSION 4.4.1修复 front matter defaults 中被 glob 匹配路径的行为回归。将主版本浓缩为一张速查表版本发布日期核心里程碑v0.1.02008-11-05首次发布Textile 文章、静态页、二进制复制v1.0.02013-05-06CLI 子命令化、jekyll new、_draftsv2.0.02014-05-06Collections、mercenary、Rouge/Sass/Kramdown、front matter defaultsv3.0.02015-10-26增量重建、Hooks、Liquid profiler、JRubyv4.0.02019-08-19Jekyll::Cache磁盘缓存、移除 Pygments/Redcarpet/rdiscountv4.4.12025-01-29当前稳定版mark_lines、最低 Ruby 2.7多版本并行维护Backport 策略这份 Changelog 还有一个容易被忽略但非常重要的结构特征多个稳定分支长期并行维护。文档中大量条目以 “Backport #… for vX.Y.x” 的固定格式出现例如v3.9.42023-12-28Backport #9392 —— 为 3.9.x 增加 Ruby 3.3 的 Logger 支持v3.10.02024-06-23Backport csv 依赖#9616、为 3.x 系列加入 webrick 依赖#9620v4.3.42024-09-16将 wdm 约束放宽#9662与 theme-gem 根目录仅在开发环境渲染#9680两项 4.4 的修复反向移植回 4.3.x。从源码结构看这些分支对应仓库中的3.9-stable、4.3-stable等长期维护线Changelog 的 Development Fixes 中多次出现 “allow releases development on*-stablebranches” 的记录。对使用者的实际意义是低版本用户尤其锁定旧版本运行环境的部署平台并非被抛弃安全与关键修复仍会周期性回流。安全修复的回移链是这一策略最典型的体现。2018 年围绕include标签绕过EntryFilter#filter符号链接检查的漏洞分别回填到 v3.6.3#7229、v3.7.4#7224、v3.8.4#7228主线的对应修复在 v4.0.0 记录为 #7226v3.8.6 还单独设有 “Security Fixes” 小节修复 theme gem 目录符号链接问题#7424。阅读 Changelog 时若看到同一 issue 编号出现在多个版本下基本可以判定为一次跨分支的批量安全回移。如何高效阅读这份 Changelog锚点直达版本。每个版本标题下都有 Kramdown 属性列表形式的锚点如{: #v4-4-1}、{: #v3-0-0}小节标题也有锚点如{: #bug-fixes-v4-4-0}文档站中可通过/docs/history/#v4-0-0这类深度链接直接跳转到某个版本或某个版本下的 Bug Fixes 小节。先按类别定位。想确认“某特性何时引入”只看 Enhancements排查旧环境升级后的行为变化则重点看 Bug Fixes 与 Forward Ports后者标明变更是从旧稳定分支前向合并来的可能影响行为一致性。追踪 issue 编号。每条记录尾部的编号即上游 issue/PR例如 4.4.1 的 “Restore globbed path behavior in front matter defaults (#9762)”可以据此找到完整的讨论与补丁上下文。注意 “REVERTS”“REPEALED” 标记。Changelog 中会显式标注被后续变更撤销的条目如 1.0.0 中的 “REPEALED by (#977)”2.3.0 中 “Ignore subfolders in the_postsfolder … REVERTS (#2633)”这是避免按过期行为写代码的重要线索。生成机制从 History.markdown 到 history 页面docs/_docs/history.md 的 front matter 声明了它由 History.markdown 生成具体管线定义在仓库根目录的 Rakefile 中入口任务是 rake/site.rake 里的site:history第 63–66 行desc Create a nicely formatted history page for the jekyll site based on the repo history. task :history do siteify_file(History.markdown, { title History }) endsite:history被site:generated_pages聚合第 10 行而site:preview/site:generate都依赖它——也就是说每次本地构建文档站History 页面都会随 History.markdown 的最新内容重新生成。转换管线在 Rakefile 中以converted_history编排第 90–100 行按顺序执行五步normalize_bullets第 45–49 行把 release-please 风格的两空格缩进*项目符号统一规范为-linkify/linkify_prs第 51–57 行把正文中裸露的#9762之类的 PR 编号转成#9762链接——{{ site.repository }}是 Liquid 变量在文档站构建时才被解析为仓库地址这解释了为什么源文件中看不到完整 URLliquid_escape第 63–65 行将记录文本中出现的 Liquid 代码如{{ page.collection }}包裹进{% raw %}...{% endraw %}防止 Changelog 内容被文档站当作模板执行——这也是你在 docs/_docs/history.md 中能看到大量{% raw %}标记的原因custom_release_header_anchors第 67–78 行为## X.Y.Z / YYYY-MM-DD版本标题追加{: #vX-Y-Z}锚点、为### 小节追加{: #小节名-vX-Y-Z}锚点且同时兼容 release-please 新格式## X.Y.Zremove_head_from_history第 84–88 行截掉第一个正式版本号之前的所有内容。最后siteify_file第 102–117 行为内容补上 front mattertitle、permalink、note: This file is autogenerated...并写入docs/_docs/history.md。这条管线揭示了一个重要细节History.markdown 顶部的## HEAD小节当前第 1–35 行永远不会出现在 History 页面中。它用于累积尚未打版本的 master 分支变更例如当前的 HEAD 段记录了post_url标签可接收 Liquid 变量#9776、.ruby-lsp加入默认排除列表#9914、允许按集合单独配置 future 元数据#9925、include_relative缓存规避#9784等。换言之## HEAD是“下一个版本”的预览窗口而 History 页面只呈现已定版的版本历史。版本信息的实际用法确认当前运行版本。仓库中版本号的唯一来源是 lib/jekyll/version.rbJekyll::VERSION 4.4.1jekyll.gemspec 通过require_relative lib/jekyll/version复用同一常量docs/latest_version.txt与文档站配置中的版本号也由site:latest_version任务从该常量同步见 rake/site.rake 第 92–101 行。本地执行jekyll --version或查看gem list jekyll的结果若与 History 页面顶部条目不一致说明运行的是旧版 gem需要bundle update jekyll。核对运行环境与依赖基线。以当前 jekyll.gemspec 为准Jekyll 4.4.x 要求required_ruby_version 2.7.0运行时依赖包括kramdown ~ 2.3、liquid ~ 4.0、rouge 3.0, 5.0、jekyll-sass-converter 2.0, 4.0、webrick ~ 1.7以及 4.4.0 起显式声明的csv、json、base64——这些依赖与 Changelog 中 4.4.0 的 Minor Enhancements 条目一一对应说明 History 页面并非孤立的文字记录而是与 gemspec 可互相印证的实现事实。规划升级路径。由于 4.0.0 移除了 Pygments/Redcarpet/rdiscount 与旧 Ruby 版本从 3.x 升到 4.x 是破坏性升级仓库专门提供了 docs/_docs/upgrading/3-to-4.md 迁移指南与 History 中 4.0.0 的 Major Enhancements 清单互为表里仍停留在 3.x 的站点则应关注对应稳定线3.9.x / 3.10.x的 Backport 条目以了解安全修复的覆盖范围。预览即将发布的内容。在正式版本发布前直接查看 History.markdown 的## HEAD段比看 History 页面更新——后者按生成管线的定义会主动丢弃该段。小结docs/_docs/history.md 既是 Jekyll 十七年演进的完整档案也是理解该项目工程实践的一扇窗从 v0.1.0 到 v4.4.1Jekyll 完成了从“Textile 文章转换器”到“带磁盘缓存、Hooks、增量重建、gem 主题体系的现代静态站点生成器”的演进四个主版本各自有清晰的技术主题2.0 的 Collections、3.0 的增量重建与 Hooks、4.0 的缓存化与依赖清理、4.4 的 Ruby 2.7 基线与高亮增强文档中密集的 Backport 条目与成组出现的安全修复揭示了 3.x/4.x 多条稳定分支并行维护的策略页面本身由 Rakefile 定义的“符号规范化 → PR 链接化 → Liquid 转义 → 版本锚点 → 裁剪 HEAD”五步管线从 History.markdown 自动生成site:history任务嵌入文档站的每次构建流程保证了 Changelog 与仓库提交记录始终同步对使用者而言配合 lib/jekyll/version.rb、jekyll.gemspec 与## HEAD预览段这份 Changelog 足以支撑版本选型、升级决策与安全补丁核查三类常见工程任务。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考