0001 采用 Zensical (Modern 变体) 升级文档编译内核
Status (状态)
Accepted (已采纳)
Context and Problem Statement (背景与问题)
现有文档系统采用 MkDocs Material 作为静态渲染器,面临以下既定演进事实:
1. 官方生命周期演进:Material for MkDocs 将于 2027 年 5 月 5 日正式到达 EOL(End of Life),其原作者团队已转向开发以 Rust 为核心的高性能继任者 Zensical;
2. 构建性能跃迁:随着文档规模扩张,Python 单线程构建耗时较长,而 Zensical 基于 Rust 内核可将单次增量构建压缩至 0.2 秒级;
3. 视觉设计现代化:Zensical 带来全新 modern 变体,具备更平滑的排印、更紧凑的间距、原生优化的代码块与暗色主题体验。
Decision Drivers (决策考量)
- 100% 配置与内容兼容:必须无缝解析既有
mkdocs.yml配置、PyMdown 扩展与 Markdown 内容; - 版本严格受控:在 0.1.x 早期阶段必须严格锁死版本号,防止自动漂移升级破坏构建;
- 无缝衔接同源图床:必须与已有的 Cloudflare Pages Function 静态资产放行策略(
/assets/stylesheets/等)100% 契合。
Considered Options (备选方案评估)
- 方案 A (继续留守 MkDocs Material 直至 2027 EOL): 虽然稳定,但放弃了数倍的构建加速与 Modern 排版红利,最终仍需在 2027 年强制迁移。
- 方案 B (即刻切换至 Zensical Modern 变体,保留 MkDocs 作为安全兜底): 精确锁定
zensical==0.1.2,直接接入 Rust 极速编译与 Modern 视觉体系,同时保留配置文件的向后兼容性。
Decision Outcome (决策结果)
Chosen option: 方案 B (Zensical Modern 变体)。
Positive Consequences (正面收益)
- 极致构建速度:全库构建耗时由 ~0.55s 骤降至 ~0.19s,提升近 300%;
- 现代美学升级:Modern 变体提供更具科技感的排印与视觉质感;
- 超前消灭技术债:在 2027 官方 EOL 到来前提前完成平滑割接。
Negative Consequences / Trade-offs (负面影响或妥协)
- Zensical 0.1.x 暂未开放第三方外部插件生态,项目须恪守“仅使用官方已原生内置插件(awesome-pages, search, pymdownx)”的约束;
- 构建与部署依赖中须增加 Rust/Wheel 运行时包(
zensical==0.1.2与zensical-ui)。