English
最后更新：2026-07-23
维护者：mdPress 产品团队
版本规划总览
v0.1.0 ██████████████████████████████████████████ 已发布
v0.2.0 ██████████████████████████████████████████ 已发布（2026-03-19）
v0.3.0 ██████████████████████████████████████████ 已发布（2026-03-19）
v0.3.1 ██████████████████████████████████████████ 已发布（2026-03-19）
v0.4.0 ██████████████████████████████████████████ 已发布（2026-03-19）
v0.4.1 ██████████████████████████████████████████ 已发布（2026-03-19）
v0.4.2 ██████████████████████████████████████████ 已发布（2026-03-19）
v0.4.3 ██████████████████████████████████████████ 已发布（2026-03-19）
v0.5.0 ██████████████████████████████████████████ 已发布（2026-03-20）
v0.5.1 ██████████████████████████████████████████ 已发布（2026-03-21）
v0.5.2 ██████████████████████████████████████████ 已发布（2026-03-22）
v0.5.3 ██████████████████████████████████████████ 已发布（2026-03-23）
v0.5.4 ██████████████████████████████████████████ 已发布（2026-03-23）
v0.6.0 ██████████████████████████████████████████ 已发布（2026-03-23）
v0.6.1 ██████████████████████████████████████████ 已发布（2026-03-24）
v0.6.2 ██████████████████████████████████████████ 已发布（2026-03-25）
v0.6.3 ██████████████████████████████████████████ 已发布（2026-03-25）
v0.6.4 ██████████████████████████████████████████ 已发布（2026-03-26）
v0.6.5 ██████████████████████████████████████████ 已发布（2026-03-27）
v0.6.6 ██████████████████████████████████████████ 已发布（2026-03-27）
v0.6.7 ██████████████████████████████████████████ 已发布（2026-03-27）
v0.6.8 ██████████████████████████████████████████ 已发布（2026-03-28）
v0.6.9 ██████████████████████████████████████████ 已发布（2026-03-28）
v0.7.0 ██████████████████████████████████████████ 已发布（2026-03-28）
v0.7.1 ██████████████████████████████████████████ 已发布（2026-03-29）
v0.7.2 ██████████████████████████████████████████ 已发布（2026-03-30）
v0.7.3 ██████████████████████████████████████████ 已发布（2026-04-01）
v0.7.4 ██████████████████████████████████████████ 已发布（2026-04-04）
v0.7.5 ██████████████████████████████████████████ 已发布（2026-04-06）
v0.7.6 ██████████████████████████████████████████ 已发布（2026-04-13）
v0.7.7 ██████████████████████████████████████████ 已发布（2026-04-15）
v0.7.8 ██████████████████████████████████████████ 已发布（2026-04-18）
v0.7.9 ██████████████████████████████████████████ 已发布（2026-04-19）
v0.7.10 ██████████████████████████████████████████ 已发布（2026-05-08）
v0.7.11 ██████████████████████████████████████████ 已发布（2026-06-17）
v0.7.12 ██████████████████████████████████████████ 已发布（2026-07-05）
v0.7.13 ██████████████████████████████████████████ 已发布（2026-07-05）
v0.7.14 ██████████████████████████████████████████ 已发布（2026-07-10）
v0.7.15 ██████████████████████████████████████████ 已发布（2026-07-22）
v0.8.0 ██████████████████████████████████████████ 已发布（2026-07-23）
v0.8.1 ██████████████████████████████████████████ 已发布（2026-07-23）
v0.8.2 ██████████████████████████████████████████ 已发布（2026-07-24）
v1.0.0 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ 规划中（目标 2027-Q1）
发布日期：2026-03
主题：核心构建管线
v0.1.0 确立了 mdPress 的基础架构，实现了从 Markdown 到 PDF 的完整转换流程。
已完成功能
| 功能 | 说明 |
|---|
| Markdown → PDF 转换 | 基于 Chromium 渲染引擎，输出质量媲美专业排版 |
| GFM 全语法支持 | 表格、任务列表、脚注、删除线、自动链接 |
| book.yaml 配置系统 | 书籍元数据、章节列表、样式配置、输出选项 |
| 自动目录生成（TOC） | 从标题层级构建，支持页码和超链接 |
| 封面页生成 | 书名、作者、版本、日期、封面图片、背景色 |
| 代码语法高亮 | 基于 chroma，100+ 编程语言，多种配色方案 |
| 多章节合并 | 配置文件定义章节顺序，支持嵌套子章节 |
| 主题系统 | 内置 technical、elegant、minimal 三套主题 |
| 图片处理 | 本地和远程图片自动 base64 嵌入 |
| 交叉引用 | 图表编号 {#fig:id} 和引用 {{ref:id}} |
| 页眉页脚 | 支持模板变量（页码、章节标题、书名） |
mdpress init | 项目初始化，生成示例配置和 Markdown 文件 |
mdpress themes | 主题列表和管理 |
| 多页面尺寸 | A4、A5、Letter、Legal、B5 |
| 自定义 CSS | 支持外部 CSS 文件覆盖样式 |
| GLOSSARY.md | 术语表支持，自动高亮术语并生成附录 |
| CI/CD 集成 | GitHub Actions 工作流配置 |
发布日期：2026-03-19
主题：降低使用门槛，扩展输出能力
v0.2.0 将 mdPress 从"PDF 生成工具"升级为"多格式图书构建平台"，重点提升易用性和生态兼容性。
已完成功能
| 功能 | 优先级 | 说明 |
|---|
| HTML 单页输出 | P0 | --format html 生成自包含单页 HTML，作为最稳定的 HTML 构建路径 |
| GitHub 仓库源支持 | P0 | 直接从 GitHub 仓库 URL 拉取内容并构建，无需本地 clone |
| SUMMARY.md 兼容 | P0 | 支持 GitBook 风格章节结构，并持续收敛真实项目迁移兼容性 |
| 零配置自动发现 | P0 | 无 book.yaml 时自动扫描 .md 文件，按约定规则排序构建 |
| serve 实时预览 | P0 | 本地 HTTP 服务器 + 文件监听 + WebSocket 自动刷新 |
site 输出收口 | P0 | 明确 html、serve、site 三条路径的职责，并补齐主流程能力 |
doctor 命令 | P1 | 提供环境和项目可构建性的快速检查 |
改进
| 改进项 | 说明 |
|---|
--format 参数 | 支持 pdf、html 及逗号分隔的多格式同时输出 |
--output 参数 | 为 build 提供统一的输出路径或前缀控制 |
| 错误信息优化 | 所有错误附带修复建议 |
| CI/CD 模板 | 提供 GitHub Actions 和 GitLab CI 的构建模板 |
里程碑
2026-03-19 正式发布 v0.2.0 ✓
发布日期：2026-03-19
主题：扩展输出格式，开放扩展能力
v0.3.0 将 mdPress 扩展为真正的多格式出版平台，引入了插件架构和对数学公式、图表的一等支持。
已完成功能
| 功能 | 优先级 | 说明 |
|---|
| ePub 3 输出 | P0 | 标准 ePub 3 电子书，支持封面、目录、元数据 |
| 插件系统 | P0 | 完整插件生命周期，支持外部进程加载和钩子注册 |
| KaTeX 数学公式 | P1 | 行内 ($...$) 和块级 ($$...$$) LaTeX 数学公式，基于 KaTeX 渲染 |
| Mermaid 图表 | P1 | 所有 HTML 输出中原生 Mermaid 渲染；validate 自动进行 Mermaid 语法检查 |
| GitBook 迁移工具 | P1 | mdpress migrate 将 GitBook 项目转换为 mdPress 格式 |
多格式 all 快捷方式 | P1 | --format all 一条命令构建 PDF、HTML、站点和 ePub |
| GitHub Actions 模板 | P2 | 预构建的 CI 自动化构建工作流 |
| 修复 | 说明 |
|---|
| CJK PDF 字体嵌入 | 注入 @font-face + file:// URL 规则，解决 Chrome 无法嵌入 CJK 字形的问题 |
| TOC 深度控制 | 新增 output.toc_max_depth 配置项，控制目录标题层级 |
| 智能输出文件名 | 根据书籍标题自动生成输出文件名，不再默认 output.pdf |
| 正则表达式性能 | 将 crossref、glossary、markdown、image 中的正则提升为包级变量 |
| Git 作者回退 | 未指定作者时自动读取 git config user.name |
发布日期：2026-03-19
主题：性能优化，零依赖 PDF
已完成功能
| 功能 | 优先级 | 说明 |
|---|
| Typst 后端 | P2 | 用 Typst 替代 Chromium 生成 PDF，实现真正的零外部依赖 |
| 增量编译 | P2 | 缓存已编译章节，仅重新编译修改过的文件 |
| 并行构建 | P2 | 多章节并行解析和渲染，利用多核 CPU |
| PDF 水印 | P2 | 支持文字水印，支持透明度控制 |
| 自定义页边距 | P2 | 支持四边独立设置，多单位支持 |
| PDF 书签 | P2 | 从标题层级自动生成书签，增强导航体验 |
| 构建缓存 | P2 | 基于文件 hash 的缓存系统，避免重复构建 |
| PlantUML 支持 | P2 | 自动检测和渲染代码块中的 PlantUML 图表 |
Typst 是用 Rust 编写的新一代排版系统，与 Chromium 方案对比如下：
| 维度 | Chromium 方案（现有） | Typst 方案（v0.4.0） |
|---|
| 外部依赖 | 需要 Chrome/Chromium | 无（内嵌或调用 typst CLI） |
| 排版质量 | 优秀（Web 标准） | 优秀（专业排版） |
| 中文支持 | 优秀 | 优秀 |
| 构建速度 | 中等（启动浏览器有开销） | 快（原生编译） |
| 二进制大小 | 小（不含 Chromium） | 可能增大（含 Typst 库） |
| CSS 兼容 | 完整 | 需要适配 Typst 样式语法 |
CLI 方向（已实现）：--format pdf 使用 Chromium（默认 PDF 后端），--format typst 使用 Typst 作为替代 PDF 后端。
增量编译方案
.mdpress-cache/
├── manifest.json # 文件 hash → 编译产物映射
├── ch01.html # 缓存的章节 HTML
├── ch02.html
└── ...
增量编译流程：
- 计算每个章节文件的 SHA-256 hash
- 对比 manifest.json 中的缓存记录
- 仅重新编译 hash 变化的章节
- 合并缓存和新编译的章节
- 生成最终输出
预期效果：500 页图书修改单个章节后，重建时间从 120 秒降至 10 秒以内。
发布日期：2026-03-20
主题：离线能力与测试覆盖基础
v0.5.0 修复了企业用户最关键的痛点（离线 PlantUML 渲染），修复了 Release CI 流水线，并建立了 golden test 框架以防止后端回归。
已交付功能
| 功能 | 优先级 | 说明 |
|---|
| PlantUML 本地渲染 | P1 | renderLocal() 调用本地 plantuml CLI 或 plantuml.jar；通过 plantuml.use_local: true 启用 |
| Golden test 框架 | P2 | tests/golden/ 快照回归测试；通过 -update 参数重新生成基准文件 |
| doctor 检测 PlantUML | P1 | mdpress doctor 检测本地 PlantUML 可用性并输出安装提示 |
| CI Node.js 24 升级 | P0 | goreleaser-action@v7、codecov-action@v5，赶在 2026-06-02 强制截止日前完成 |
| Release CI Docker 修复 | P0 | 删除残留的 Docker Hub 登录步骤；镜像仅发布至 GHCR |
测试覆盖里程碑
| 包 | v0.4.3 | v0.5.0 | 提升 |
|---|
internal/plantuml | 54.8% | 75%+ | +20 pp |
internal/source | 41.2% | 62%+ | +21 pp |
cmd | 47.7% | 60%+ | +12 pp |
| 整体 | 62.3% | ≥ 68% | +6 pp |
发布日期：2026-03-21
主题：UI 优化和 bug 修复
v0.5.1 提供了手风琴式侧边栏导航改进，并修复了影响 PlantUML 渲染、SUMMARY.md 标题处理和迁移工作流的关键上下文传播问题。
已完成功能
| 功能 | 优先级 | 说明 |
|---|
| 手风琴式侧边栏导航 | P1 | 展开章节时自动收起同级兄弟节点，提供更清爽的 GitBook 式导航体验 |
| 平滑的侧边栏过渡效果 | P2 | CSS 过渡升级至 Material Design 缓动曲线，展开/收起动画体验更佳 |
修复项
| 修复 | 优先级 | 说明 |
|---|
| PlantUML 上下文传播 | P0 | 使用调用者提供的 context 替代 context.Background()，确保构建超时和取消信号正确传播 |
| 通用 SUMMARY.md 标题过滤 | P0 | 现已正确识别"在线阅读"、"Read Online"、"Contents" 等通用导航标题并跳过 |
| book.json 标题优先级 | P1 | 当 book.json 提供标题时，在自动发现时不再被 README.md 推理覆盖 |
README 中缺失 migrate 命令 | P1 | 将 migrate 命令添加到中英文 README 的"All Commands"表格中 |
| GitLab CI lint 版本不匹配 | P2 | 将 golangci-lint 从 v2.1 升级至 v2.11.3 以匹配 GitHub Actions |
| 完成命令中的拼写错误 | P2 | 修正注释中 behaviour → behavior |
发布日期：2026-03-22
主题：跨平台稳定性和 CI 可靠性
v0.5.2 通过 PATHEXT 插件可执行文件解析改进 Windows 支持，修复跨平台测试失败问题，并将所有 GitHub Actions 升级至最新主版本以加固 CI 供应链。
已完成功能
| 功能 | 优先级 | 说明 |
|---|
| Windows 插件可执行文件解析 | P1 | 无扩展名的插件路径自动按 PATHEXT 尝试 .exe、.bat、.cmd |
| 搜索焦点样式和无障碍焦点陷阱 | P2 | 改进键盘无障碍体验，增加可见焦点指示器 |
修复项
| 修复 | 优先级 | 说明 |
|---|
| 跨平台测试路径 | P0 | 用 t.TempDir() 替换硬编码 Unix 路径，修复 Windows CI 失败 |
| Codecov action 参数名 | P1 | 将 file 修正为 files 以兼容 codecov-action@v5 |
| Dependabot 配置语法 | P1 | 将无效的 pull-requests.max-number 修正为 open-pull-requests-limit |
| ePub 测试资源泄漏 | P2 | 补充缺失的 reader.Close() |
发布日期：2026-03-23
主题：bug 修复和文档对齐
v0.5.3 修复了站点输出中关键的代码块渲染问题，并更新了项目文档。
修复项
| 修复 | 优先级 | 说明 |
|---|
| 代码块文本不可见 | P0 | Chroma 语法高亮器在 <pre> 标签上注入了内联 style="background-color:#fff"，导致代码块不可读。修复移除了 Chroma 在后处理中的内联样式 |
| 站点代码块配色方案 | P1 | 将站点输出的代码块从深色主题改为浅色主题（#f6f8fa 背景、#24292e 文本），与 Chroma 的"github"调色板匹配 |
变更
| 变更 | 说明 |
|---|
| 文档更新 | 更新 ARCHITECTURE 文档版本，修复 ROADMAP 版本顺序，在 README 表格中添加 Typst 格式 |
| 删除过时文档 | 删除了引用 v0.4.3 的过时 NEXT-STEPS.md 规划文档 |
发布日期：2026-03-23
主题：丰富站点功能，安全加固
v0.5.4 是站点输出格式的重大功能更新，新增客户端全文搜索、暗色模式、面包屑导航、页面目录、代码复制按钮和 SEO 优化。同时修复了 ePub 资源泄漏、UTF-8 截断和开发服务器 symlink 路径穿越漏洞等问题。
新增功能
| 功能 | 优先级 | 说明 |
|---|
| 全文搜索 | P0 | 客户端搜索，支持 Cmd/Ctrl+K 快捷键、键盘导航和结果高亮 |
| 暗色模式 | P0 | 三态主题切换器（亮色/暗色/跟随系统），状态持久化 |
| SEO meta 标签 | P1 | 自动生成描述和 Open Graph 标签 |
| Sitemap 生成 | P1 | sitemap.xml 支持搜索引擎索引 |
| 面包屑导航 | P1 | 页面层级路径显示 |
| 页面目录侧栏 | P1 | "本页内容"侧栏，基于 IntersectionObserver 滚动高亮 |
| 代码复制按钮 | P1 | 悬停显示复制按钮，集成剪贴板 API |
| 侧边栏折叠 | P2 | 桌面端侧边栏可折叠，状态持久化 |
| 图片懒加载 | P2 | 自动为所有 <img> 标签添加 loading="lazy" |
| CJK 标题 ID | P1 | 自定义标题 ID 生成器，保留 Unicode 字符 |
修复项
| 修复 | 优先级 | 说明 |
|---|
| ePub zip writer 资源泄漏 | P1 | 所有错误路径添加 defer w.Close() |
| SVG 封面 UTF-8 截断 | P1 | 用 rune 截断替代字节截断 |
| SVG XML 属性转义 | P2 | 补充 " 和 ' 实体转义 |
| Symlink 路径穿越 | P1 | serve 路径检查添加 filepath.EvalSymlinks() |
| 滚动行为回归 | P2 | 修复三元表达式始终返回 'auto' 而非 'smooth' |
| 描述 meta 截断 | P2 | 使用 rune 截断保护多字节字符 |
发布日期：2026-03-23
主题：生产就绪基础
v0.6.0 是从功能驱动开发（v0.1–v0.5）向生产就绪 v1.0.0 过渡的关键版本。
交付功能
| 功能 | 优先级 | 说明 |
|---|
mdpress upgrade 命令 | P0 | 从 GitHub 发布自动升级，支持平台检测、SHA-256 校验和验证、--check 检查模式 |
mdpress doctor 增强 | P0 | 新增六项环境检查：Go 版本（≥1.26）、Git 可用性、网络连接、磁盘空间、CJK 字体检测、插件健康检查；新增 --verbose 标志 |
| 中英双语用户手册 | P0 | 完整的中英双语用户手册（60+ Markdown 文件），使用 mdPress 自身构建 |
ParseVersionPart 工具函数 | P2 | 可复用的版本字符串解析器，供 doctor 和 upgrade 命令使用 |
改进项
| 改进 | 优先级 | 说明 |
|---|
| 路径穿越防护加固 | P1 | LocalSource.Prepare() 现在验证子目录路径以防止穿越攻击 |
| 跨平台路径处理 | P1 | HasLangsFile 中用 filepath.Join 替代字符串拼接，修复 Windows 兼容性 |
| 文档更新 | P2 | README 命令表（中英文）和 COMMANDS 文档中添加 upgrade 命令 |
修复项
| 修复 | 优先级 | 说明 |
|---|
| Lint 清理 | P2 | 移除 cmd/*_test.go 中重复的测试辅助函数和未使用的导入 |
| 中文截断测试修复 | P2 | 增大输入长度以正确覆盖 ≥160 字符的截断路径 |
测试
- 新增 1,500+ 行测试代码，涵盖 12 个文件
upgrade 命令完整覆盖：版本比较、资源选择、下载和二进制替换- 扩展
doctor、cmd、themes、quickstart、validate 测试
file、cjk、image 包的综合工具函数测试- 扩展插件生命周期和错误路径测试
发布日期：2026-03-24
主题：质量与一致性
v0.6.1 是补丁版本，修复了 v0.6.0 中发现的 Bug 并完善了文档覆盖。
修复项
| 修复 | 优先级 | 说明 |
|---|
| Typst 超时配置 | P0 | compileToPDF() 现在使用配置的 g.timeout 而非硬编码 120 秒 |
| Typst 格式验证 | P0 | validFormats 中添加 typst，使 book.yaml 可接受 typst 输出格式 |
| Git 分支名验证 | P1 | 分支名正则要求首字符为字母或数字，防止 CLI 标志注入 |
| ePub 清理错误处理 | P1 | 构建失败时 os.Remove 错误现在记录日志而非静默忽略 |
| 错误信息一致性 | P2 | 将 parser.go 和 crossref.go 中残余中文错误信息替换为英文 |
| GoReleaser Homebrew URL 大小写 | P2 | 将 Homebrew Cask 中的 mdPress 更正为 mdpress |
| Gosec 规则排序 | P2 | .golangci.yml 中 gosec 规则排除项按数字升序排列 |
文档
| 变更 | 说明 |
|---|
| Doctor 命令文档 | 更新 doctor.md 和 doctor_zh.md，补充所有 v0.6.0 环境检查项 |
| README 添加用户手册链接 | 在中英文 README 中添加双语用户手册链接 |
COMMANDS 添加 version 命令 | 在命令矩阵和层级图中补充 version 命令 |
| ROADMAP 更新 | 补充 v0.6.0 和 v0.6.1 发布说明 |
.gitignore 增强 | 添加 .agent/、.env 和凭证文件忽略规则 |
发布日期：2026-03-25
主题：安全与正确性
v0.6.2 是安全加固版本，对预览服务器、升级命令、图片处理和主题 CSS 进行了注入和穿越攻击防护，同时修复了大量解析器、缓存和渲染 Bug。
安全修复
| 修复 | 优先级 | 说明 |
|---|
| WebSocket Origin 验证 | P0 | 预览服务器验证 Origin 头与 Host 匹配，防止跨域 WebSocket 劫持 |
| 升级 URL 域名验证 | P0 | 二进制下载时验证 URL 指向 github.com 或 *.githubusercontent.com |
| 绝对图片路径拒绝 | P1 | resolveLocalImagePath 拒绝绝对路径，防止读取任意本地文件 |
| 主题 CSS 注入防护 | P1 | 主题颜色和字体值在 CSS 输出前验证是否包含不安全字符 |
| CSS 颜色模式收紧 | P1 | rgb()/hsl() 模式限制括号内容为安全字符 |
| 安全响应头 | P2 | 预览服务器设置 X-Content-Type-Options: nosniff 和 X-Frame-Options: DENY |
修复项
| 修复 | 优先级 | 说明 |
|---|
| 章节缓存键不匹配 | P0 | 缓存键使用与解析器相同的回退逻辑，防止过期缓存命中 |
| PlantUML 编码 | P0 | 使用正确的原始 deflate 和 PlantUML 自定义 6 位编码字母表 |
| 标题 ID 竞态条件 | P0 | 每次 Transform 调用使用本地 usedIDs map 而非共享状态 |
| book.json 路径穿越 | P1 | safeJoin() 拒绝绝对路径和逃逸路径 |
| Typst 字体大小回退 | P1 | 解析失败时回退为 12pt 而非不可见的 0.0pt |
| 术语表双重包装 | P1 | 重叠术语不再生成嵌套 <span> 标签 |
| UTF-8 标题大写 | P1 | 使用 []rune + unicode.ToUpper 处理多字节首字符 |
| Typst 模板注入 | P1 | 包含 {{ }} 的用户内容不再 panic 或注入代码 |
变更
| 变更 | 说明 |
|---|
| 消除三次配置加载 | doctor 命令一次加载配置后传递使用 |
| 移除死代码 | 删除未使用的 CacheStatistics、空操作 convertCodeSpans 和重复 fileExists |
| 术语表正则提升 | skipPattern 在包级别编译一次 |
| 搜索索引优化 | 用 utf8.RuneCountInString() 替换 len([]rune(...)) |
文档
| 变更 | 说明 |
|---|
| validate 命令 | 补充 --report 标志文档 |
| completion 命令 | 将 --no-descriptions 支持从 bash/zsh 更正为 bash/fish |
| build 命令 | 补充 --format all 展开为 pdf,html,site,epub,typst 的说明 |
| upgrade 命令 | 移除虚构的退出码章节 |
发布日期：2026-03-25
主题：安全性与搜索用户体验
v0.6.3 针对 SSRF、XSS、路径遍历和模板注入进行安全加固，同时将搜索 UI 重新设计为右侧面板。
安全修复
| 修复 | 优先级 | 说明 |
|---|
| PlantUML SSRF 防护 | P0 | 通过 DNS 解析验证 PlantUML 服务器 URL 是否指向私有/回环地址 |
| Mermaid XSS 修复 | P1 | 在 Mermaid 代码块中反转义后重新转义 HTML 实体 |
| EPUB 路径遍历防护 | P1 | 拒绝绝对路径并验证相对路径不会逃逸源目录 |
| Tar 路径遍历防护 | P1 | 升级解压时跳过包含 .. 的条目 |
| 模板注入防护 | P1 | 清除 Typst 元数据和尺寸字段中的 {{ 和 }} |
| 配置字段验证 | P1 | 验证 font_family、font_size 和 code_theme 防止注入 |
| 自定义 CSS 大小限制 | P2 | 限制自定义 CSS 文件读取上限为 1 MB |
| URL 方案验证 | P2 | openBrowser 仅允许 http 和 https 方案 |
问题修复
| 修复 | 优先级 | 说明 |
|---|
| 子页面搜索失效 | P0 | 搜索索引改用绝对路径获取 |
| 搜索结果链接错误 | P0 | 搜索结果链接使用绝对路径 |
| 边界检查差一错误 | P1 | 修复 EPUB 和图片正则的子匹配访问 |
| 未检查的类型断言 | P1 | PlantUML 缓存使用 comma-ok 模式 |
| GitHub 临时目录泄漏 | P1 | 验证失败时清理临时目录 |
变更
| 变更 | 说明 |
|---|
| 搜索重设计为右侧面板 | 搜索以 GitBook 风格的右侧面板打开 |
| 防御性切片复制 | Plugins() 返回副本防止外部修改 |
| 协程 panic 恢复 | 图片预取协程添加 panic 恢复 |
发布日期：2026-03-26
主题：PDF 图片和图表渲染
v0.6.4 修复了 PDF 渲染中的关键问题，包括图片缺失、Mermaid 图表文字丢失、SVG 徽章文字不可见和布局问题。
问题修复
| 修复 | 优先级 | 说明 |
|---|
| PDF 图片未渲染 | P0 | PDF 生成前移除 loading="lazy" 属性 |
| Mermaid 图表文字缺失 | P0 | 移除破坏箭头和标签的 HTML 重转义 |
| PDF 中 Mermaid 数字/拉丁字符缺失 | P1 | 在 Mermaid SVG CSS 规则中将拉丁字体置于 CJK 字体之前 |
| PDF 中 SVG 徽章 CJK 文字缺失 | P1 | 内联包含 CJK 字符的 SVG 并嵌入字体 |
| 徽章图片纵向堆叠 | P1 | block display 仅应用于独立图片 |
| mdPress 文档被注入 PDF | P1 | 自动发现时过滤 CHANGELOG.md 等文件 |
| 封面版本号默认为 1.0.0 | P1 | 从 book.json 读取版本号，以 git describe 作为后备 |
| 封面重复品牌标识 | P2 | 移除封面内联品牌页脚 |
发布日期：2026-03-27
主题：纵深安全防御与正确性
v0.6.5 在插件系统、Mermaid 渲染、Typst 后端、升级管道和 git 集成中新增五项安全加固措施，并修复了 GitBook 迁移错误和搜索索引性能问题。
安全修复
| 修复 | 优先级 | 说明 |
|---|
| 插件路径遍历防护 | P0 | 解析到项目目录外的相对插件路径现已被拒绝 |
| Mermaid XSS 纵深防御 | P1 | HTML 反转义后清除 Mermaid 图表中的 <script> 标签和事件处理属性 |
| Typst 输出捕获限制 | P1 | 将 typst compile 的标准输出/错误限制为 1 MB，防止恶意文档导致 OOM |
| 升级重定向 SSRF 防护 | P1 | 在升级下载期间验证 HTTP 重定向目标，防止 DNS 投毒导致 SSRF |
| Git 命令超时 | P1 | 为自动发现中的 git describe 和 git config 调用添加 5 秒超时 |
问题修复
| 修复 | 优先级 | 说明 |
|---|
| GitBook 插件迁移错误 | P1 | 迁移 book.json 时跳过 GitBook npm 插件，避免生成路径缺失的无效配置 |
| 搜索索引标题片段 | P1 | 每个章节只计算一次 rune 切片，修复多标题章节的 O(N*M) 分配问题 |
| 内联 SVG 徽章高度 | P2 | 修复内联 SVG 与 <img> 渲染之间的徽章高度不一致 |
变更
发布日期：2026-03-27
主题：渲染正确性
v0.6.6 修复了 PDF 输出中章节标题重复的问题，并改进 SUMMARY.md 解析以正确处理内联链接。
问题修复
| 修复 | 优先级 | 说明 |
|---|
| PDF 章节标题重复 | P0 | 使用 h2-h6 的子章节标题被重复，因去重逻辑仅匹配 h1；现已匹配所有标题级别 |
| SUMMARY.md 解析拾取内联链接 | P0 | 导航文本行被错误解析为章节条目；现仅接受包含直接链接的列表项 |
已交付功能
| 功能 | 优先级 | 说明 |
|---|
| 标题不匹配警告 | P1 | 当 SUMMARY.md 标题与文件首标题不同时发出 book-title-mismatch 警告；渲染输出以 SUMMARY 标题为准 |
发布日期：2026-03-27
主题：PDF 渲染正确性与安全
v0.6.7 修复了封面标题导致的 PDF 重复书签、居中布局下 README 标题去重，并确保 Mermaid 图表在 PDF 生成前完全渲染。
问题修复
| 修复 | 优先级 | 说明 |
|---|
| 封面标题重复 PDF 书签 | P0 | 封面标题从 <h1> 改为样式化 <div>，防止 Chrome 大纲生成器创建与首章重复的书签 |
| README 标题去重处理包裹标题 | P0 | stripDuplicateLeadingH1 现可在标题前有非标题 HTML 时找到首标题 |
| PDF 中 Mermaid 图表完全渲染 | P0 | 在 Chrome 打印 PDF 前添加最多 15 秒的等待步骤 |
安全修复
| 修复 | 优先级 | 说明 |
|---|
| Chrome CLI 输出捕获限制 | P1 | Chrome CLI 后备方案通过 chromeLimitedWriter 将输出限制为 10 MB |
| 符号链接感知的图片路径检查 | P1 | resolveLocalImagePath 和 EPUB 在检查前通过 filepath.EvalSymlinks 解析符号链接 |
| Git 参数注入加固 | P1 | discover.go 中的 git 命令已验证防止参数注入 |
发布日期：2026-03-28
主题：正确性与测试覆盖
v0.6.8 改进了 Markdown 解析器线程安全、升级管道的错误包装和 GitHub 源加固，并新增校验和验证与 SSRF 重定向验证的全面测试套件。
改进
| 改进 | 优先级 | 说明 |
|---|
| Markdown 解析器线程安全 | P1 | 移除不必要的 sync.RWMutex；标题通过局部状态收集，使并发 Parse 调用无需加锁 |
| 升级错误包装 | P2 | 内部错误使用 %w 替代 %v，支持调用者解包 |
| GitHub 源加固 | P1 | 读取 .gitattributes 前检查 stat + 大小，避免读取超大文件 |
测试
| 测试 | 说明 |
|---|
| 校验和验证测试 | 升级二进制校验和验证的全面测试套件 |
| SSRF 重定向验证测试 | PlantUML 重定向目标验证的测试覆盖 |
发布日期：2026-03-28
主题：PDF 渲染正确性
v0.6.9 通过无条件剥离章节内容中的前导 <h1> 消除 PDF 输出中的重复 H1 书签，因为模板已将 SUMMARY 标题渲染为章节标题。
问题修复
| 修复 | 优先级 | 说明 |
|---|
| 消除 PDF 中的重复 H1 书签 | P0 | 无条件剥离章节内容中的前导 <h1>，因模板已将 SUMMARY 标题渲染为 <h1 class="chapter-title">。此前仅在文本完全匹配时移除 |
主题：站点输出用户体验改进
已交付功能
| 功能 | 优先级 | 说明 |
|---|
| 上一页/下一页导航 | P0 | 页面底部添加前后章节导航按钮，方便连续阅读 |
| "使用 mdPress 构建" 品牌标识 | P1 | 站点输出底部添加低调的品牌链接；英文书籍显示 "Built with mdPress" |
| 可折叠侧边栏 | P2 | 侧边栏中含子页面的章节可展开/折叠 |
延期至后续版本
| 功能 | 优先级 | 说明 |
|---|
| 侧边栏章节分组 | P2 | 支持在 book.yaml 中用 parts 将章节分组显示（如"第一部分：入门篇"），支持折叠 |
发布日期：2026-03-29
主题：正确性、安全与格式提升
v0.7.1 修复了标题正则匹配、Typst 代码跨度转换和 SVG 内联的渲染错误，加固了 PlantUML 指令解析，移除了 serve 调试面板中的内部路径，并将 Typst 提升为一级输出格式。
已交付功能
| 功能 | 优先级 | 说明 |
|---|
| Typst 提升为一级输出格式 | P0 | Typst PDF 生成可通过 --format typst 使用 |
| migrate 命令 force 标志 | P1 | 添加 --force 标志在迁移时覆盖已有文件 |
| init 命令文件名清理 | P1 | 项目初始化时对文件名进行清理 |
| 升级后安装验证 | P1 | 升级安装后验证二进制完整性 |
| 站点 UX 功能 | P1 | 添加选中高亮、待处理导航和改进的客户端导航 |
安全修复
| 修复 | 优先级 | 说明 |
|---|
| PlantUML 指令和 SVG 清理加固 | P0 | 加强 PlantUML 指令解析和 SVG 内容清理 |
| serve 调试面板移除内部路径 | P1 | 移除 serve 调试面板输出中的内部文件系统路径 |
问题修复
| 修复 | 优先级 | 说明 |
|---|
| 标题正则正确匹配标签 | P0 | 修复标题正则以匹配正确的标题级别标签 |
| Typst 转换器跳过代码跨度 | P0 | 防止内联代码跨度中进行 Typst 标记转换 |
| 嵌套 SVG 内联 | P1 | 修复包含嵌套 SVG 元素的 SVG 内联 |
| Typst 构建器使用原始 Markdown | P1 | 修复 Typst 构建器传递原始 Markdown 而非 HTML |
| Windows 测试路径分隔符 | P2 | 修复 Windows 兼容性的路径分隔符处理 |
改进
| 改进 | 说明 |
|---|
| Doctor 上下文和符号链接处理 | 改进 doctor 命令的上下文报告和符号链接感知检查 |
| PDF 生成器错误处理 | 检查 PDF 生成器中 tmpFile.Close 的错误 |
发布日期：2026-03-30
主题：代码现代化与跨平台可靠性
v0.7.2 在整个代码库中现代化 Go 惯用法，从已弃用的 API 迁移到现代等价物，并修复了 Windows CI 测试失败。
变更
| 变更 | 说明 |
|---|
| 现代化 Go 惯用法 | 将 os.IsNotExist 迁移为 errors.Is(err, fs.ErrNotExist)，sort 迁移为 slices 包，== io.EOF 迁移为 errors.Is |
| 移除冗余辅助函数 | 用 slices.Equal 替换自定义 equalIntSlices |
问题修复
| 修复 | 优先级 | 说明 |
|---|
| PDF 生成器过时错误消息 | P1 | 修复引用旧函数名的错误消息 |
| Windows CI 测试失败 | P0 | 修复测试中 Windows 兼容性的路径处理 |
改进
| 改进 | 说明 |
|---|
| 测试断言加强 | 为 server 和 plugin 测试中的返回值添加缺失的断言 |
| 文档同步 | 更新 ARCHITECTURE、ROADMAP、命令文档和手册版本 |
发布日期：2026-04-01
主题：安全加固与依赖更新
v0.7.3 修复了 SSRF 绕过向量，将 Go 工具链升级至 1.26.1，并在整个代码库中现代化了八进制字面量和结构化日志。
安全修复
| 修复 | 优先级 | 说明 |
|---|
| 阻止 0.0.0.0/8 范围的 SSRF | P0 | 防止对 Linux 上可达 localhost 的"本网络"地址发起服务端请求 |
| 防护 SUMMARY.md 解析 TOCTOU | P1 | 检测文件在 stat 和读取之间增长导致的静默截断 |
变更
| 变更 | 说明 |
|---|
| 升级 Go 至 1.26.1 | 更新最低 Go 版本和所有依赖 |
| 使用显式八进制字面量 | 将 0644/0755 迁移为 0o644/0o755 |
| 使用 slog.Any 记录错误 | 在结构化日志中保留错误类型信息 |
| 更新 CI 至 Go 1.26 | 升级 GitHub Actions、GitLab CI 和 Docker 至 Go 1.26 |
| 更新 Dockerfile 至 Alpine 3.23 | 使用最新 Alpine 基础镜像 |
问题修复
| 修复 | 优先级 | 说明 |
|---|
| 处理延迟清理错误 | P2 | 正确确认延迟清理调用中被丢弃的错误返回值 |
| 修复 CI 缓存路径一致性 | P2 | 在 CI 文档示例中添加 MDPRESS_CACHE_DIR 环境变量 |
| 修复过时的插件注册表引用 | P2 | 删除迁移文档中不存在的"插件注册表"链接 |
发布日期：2026-04-04
主题：纵深防御安全加固、依赖升级、样式一致性
v0.7.4 加固了 HTML/CSS 清理器以防御高级 XSS 向量，消除了文件操作中的 TOCTOU 竞争条件，升级了 KaTeX 和 chroma，并为 standalone 和 EPUB 输出补齐了 figure/figcaption 样式。
安全修复
| 修复 | 优先级 | 说明 |
|---|
| 加固 Mermaid 清理器正则 | P0 | 修复 dangerousTagPattern 处理引号属性中的 >；扩展 jsURIPattern 替换整个 href/src 属性 |
| 阻止 CSS 中的 vbscript/协议相对 URL | P1 | 在 CSS URL 拦截器中添加 vbscript:；检测 //evil.com 协议相对 URL |
| 修复构建清单 TOCTOU | P1 | 用 io.LimitReader 替换 loadManifest 和 computeChapterHash 中的 stat+read |
| CopyFile 添加 LimitReader | P1 | 用有界读取防御 stat 和 copy 之间的文件增长 |
| 所有 HTTP 客户端使用 SSRF 安全传输 | P1 | 为 doctor 和 upgrade 命令应用 SSRFSafeTransport |
| SVG2 href 清理 | P2 | 在 PlantUML SVG 输出中剥离裸 href 和单引号外部 URL |
变更
| 变更 | 说明 |
|---|
| 升级 KaTeX 至 0.16.44 | 从 0.16.11 更新所有 CDN URL |
| 升级 chroma 至 v2.23.1 | 最新语法高亮器，改进语言支持 |
| 升级 codecov-action 至 v6 | 更新 CI 覆盖率上传 action |
| standalone HTML 中限定 KaTeX 作用范围 | 目标改为 #main-content，避免将侧边栏文本当作数学公式处理 |
| 导出 SSRFSafeTransport | 通过 utils.SSRFSafeTransport() 使 SSRF 安全传输可跨包复用 |
修复
| 修复 | 说明 |
|---|
| standalone HTML 添加 figure/figcaption 样式 | 居中图片和标题，通过 CSS 变量支持暗色模式 |
| EPUB 添加 figure/figcaption 基础样式 | 为图片、图表和标题提供内联兜底样式 |
| PlantUML 添加本地执行超时 | 防止使用无限上下文时出现无限挂起 |
发布日期：2026-04-06
主题：国际化、渲染改进与正确性
v0.7.5 为封面标签添加国际化支持（中文、日文、韩文），自动检测图表标题并应用 CSS 样式，允许字体族名使用 Unicode 字符，改进从 git 远端发现作者信息，并修复章节 HTML 生成中的 slug 冲突问题。
已交付功能
| 功能 | 优先级 | 说明 |
|---|
| 封面标签国际化 | P1 | 封面为 zh、ja、ko 语言显示本地化的作者/版本/日期标签 |
| 图表标题样式 | P1 | 以"Figure N"或"图 N"等开头的段落自动添加 class="caption" 进行居中样式 |
| Unicode 字体族验证 | P1 | 包含 CJK 字符的字体族名（如 思源黑体）现已被接受 |
| Git 远端所有者用于作者 | P2 | 自动发现优先使用 git 远端所有者，而非 README 中的 GitHub URL |
问题修复
| 修复 | 优先级 | 说明 |
|---|
| 章节 HTML slug 冲突 | P1 | 三方 slug 冲突（如两个章节 slug 化为"intro"加上自然的"intro-2"）不再覆盖文件 |
| 图片下载重试路径上下文泄漏 | P1 | 重试路径不再在读取响应体前取消上下文 |
| 升级后可执行权限 | P1 | 显式 os.Chmod 确保升级写入后二进制可执行 |
改进
| 改进 | 说明 |
|---|
| 移动测试专用辅助函数到测试文件 | 从生产代码中移除 expandString |
| 标题单元测试 | 为标题模式匹配添加表驱动测试 |
| Slug 冲突三方测试 | N 方 slug 去重的测试覆盖 |
文档
| 变更 | 说明 |
|---|
| 同步中文 ROADMAP | 在 ROADMAP_zh.md 中添加缺失的 v0.6.5-v0.6.9、v0.7.1-v0.7.2 章节 |
| 文档化 migrate 标志 | 在 CLI 参考中添加 --dry-run 和 --force 标志 |
发布日期：2026-04-13
主题：安全加固、正确性与文档同步
v0.7.6 加固配置文件加载以防止 TOCTOU 竞争条件，添加 WebSocket 预检查，防止 git 参数注入，修复站点章节树 slug 冲突，并同步架构文档与代码库。
已交付功能
| 功能 | 优先级 | 说明 |
|---|
| 配置文件 TOCTOU 加固 | P1 | 使用 Open+Fstat+LimitReader 防止配置加载时的竞争条件 |
| WebSocket 升级前预检查 | P1 | 达到连接限制时在升级前返回 HTTP 503 |
| Git 参数注入防护 | P1 | 为目录参数添加 ./ 前缀，防止以 - 开头的目录被解析为标志 |
| CSS behavior 属性清理 | P2 | 阻止旧版 IE behavior: 和 -moz-binding: CSS 注入向量 |
| Serve 网络绑定警告 | P2 | 绑定到非回环地址时发出警告 |
问题修复
| 修复 | 优先级 | 说明 |
|---|
| 站点章节树 slug 冲突 | P1 | 使用对齐的 chapterFiles 切片，在跳过章节时确保正确映射 |
| PDF 回退路径临时文件泄漏 | P1 | rename 失败时清理临时文件 |
| GITHUB_TOKEN 重复读取 | P1 | 仅读取一次 token，防止 URL 嵌入和日志脱敏之间的不一致 |
| KaTeX 作用域限制到章节内容 | P2 | 目标从 document.body 改为 .chapter-content |
| 构建失败时插件清理 | P1 | 确保构建中途失败时也释放插件资源 |
改进
| 改进 | 说明 |
|---|
| 重构 GitHub 源清理逻辑 | 提取 cleanupOnError() 和 validateSubDir() 方法以减少重复 |
| 改进链接重写规范化 | 将扩展名小写化移入 NormalizePath 以确保查找一致性 |
| 同步架构文档 | 修复 HeadingInfo 字段、LocalSource 字段名、构建清单大小写等文档与代码不一致 |
发布日期：2026-04-15
主题：补充安全加固、正确性修复与测试改进
v0.7.7 拦截封面图片中的危险 URI 协议，防止实时重载中的脚本注入，修复书签选项和水印透明度验证，并加强测试断言。
已交付功能
| 功能 | 优先级 | 说明 |
|---|
| 封面图片 URI 协议拦截 | P1 | 拦截 CSS url() 中的 javascript:、vbscript: 和 data: URI |
| 实时重载脚本注入修复 | P1 | 转义内联 JSON 中的 </ 以防止 </script> 注入 |
问题修复
| 修复 | 优先级 | 说明 |
|---|
generate_bookmarks: false 被忽略 | P1 | 始终传递文档大纲选项以确保禁用书签生效 |
| 水印透明度超出范围 | P2 | 将 [0.0, 1.0] 范围外的透明度值进行钳位处理 |
| Serve 模式插件清理 | P2 | 确保 serve 构建完成时释放插件资源 |
改进
| 改进 | 说明 |
|---|
| 加强测试断言 | 在 CJK 测试中使用 t.Fatal/t.Skip，添加 warnRecorder 模拟，添加边界和空白边缘用例 |
| 同步架构文档 | 修复 source 模块作用域和监听文件扩展名 |
发布日期：2026-04-18
主题：正确性修复、跨平台健壮性与文档同步
v0.7.8 修复 Typst 粗斜体转换、大小写不敏感的 body 标签搜索、URL 编码图片路径验证、符号链接感知的路径遍历检查，以及搜索索引和元描述中的 HTML 实体处理。
问题修复
| 修复 | 优先级 | 说明 |
|---|
| 大小写不敏感的 body 标签搜索 | P2 | 使用 EqualFold 逐字节扫描避免多字节字符小写化后的索引偏移 |
| URL 编码图片路径解码 | P2 | 验证前解码百分号编码路径 |
| Typst 粗斜体转换 | P2 | ***text*** 现在正确生成 *_text_* 而非错误输出 |
| 符号链接感知的路径验证 | P2 | 对最近存在的祖先目录解析符号链接进行包含检查 |
| 搜索索引中的 HTML 实体处理 | P2 | 反转义纯文本中的实体以确保标题查找和描述正确渲染 |
| Windows 路径验证测试 | P1 | 使绝对路径测试用例具有平台感知能力 |
改进
| 改进 | 说明 |
|---|
| 添加 Mermaid 括号诊断测试 | 全面覆盖括号匹配、嵌套、引号和注释 |
| 同步文档 | 修复变更日志链接、架构版本号和路线图排序 |
发布日期：2026-04-19
主题：跨平台可靠性
v0.7.9 修复了 Windows 平台多语言构建模式中的一个回归问题，该问题由非绝对路径导致 filepath.Rel 调用失败引起。
修复问题
| 修复 | 优先级 | 说明 |
|---|
| Windows 多语言切换器注入修复 | P1 | 在生成引导页和语言切换链接前将多语言根目录规范化为绝对路径 |
改进
| 改进 | 说明 |
|---|
| Windows 多语言回归测试覆盖 | 覆盖绝对路径规范化和斜杠标准化的语言切换链接测试（Windows 特定） |
发布日期：2026-05-08
主题：防御性编码、XSS 加固与缺陷修复
v0.7.10 是一次安全与稳定性发布。本版本加固了输出站点的 HTML/CSS 转义，预防了构建管线中的 symlink 逃逸与 TOCTOU 漏洞，并修复了多个用户可见的缺陷（配置优先级、slug 冲突、KaTeX 渲染等）。
安全修复
| 修复 | 优先级 | 描述 |
|---|
| 搜索结果摘要 XSS | P0 | 在 innerHTML 注入前对 &、>、" 与 < 一并编码 |
| 标题 HTML 实体转义 | P1 | 增加单引号 ' 编码，提升单引号属性上下文安全性 |
| CSS 转义回退扩展 | P2 | 让 polyfill 匹配 CSS.escape() 在所有 CSS 特殊字符上的行为 |
| symlink 逃逸防护 | P1 | 校验解析后的子目录路径仍在源目录根之内 |
| 主题/服务文件读取 TOCTOU | P1 | 原子读取替换 stat-then-read 模式 |
| Banner 注入大小限制 | P2 | 注入前拒绝过大的 banner 负载 |
| 插件元数据输出限制 | P2 | 限制插件元数据返回大小，防止失控输出 |
| Go 标准库安全更新 | P1 | 将 Dockerfile 与工具链升级至 Go 1.26.2 |
缺陷修复
| 修复 | 描述 |
|---|
| 保留 book.json 版本号 | 显式的 book.json 版本不再被 README 提取的版本覆盖 |
| WebSocket nil 连接 panic | sentinel 写入前对 nil 连接进行保护 |
| 多语言构建根目录 | 在不同语言变体之间正确解析构建根 |
| Slug 去重冲突 | 避免不同标题生成相同的 slug |
| 多章 KaTeX 渲染 | 章节切换时正确初始化 KaTeX |
| Typst 管线清理 | 失败时移除部分 PDF，处理嵌入换行 |
| PlantUML 错误链 | 用 %w 包装原始错误，保留错误链 |
| 剪贴板/CDN 回退 | 浏览器 API 或 CDN 不可用时优雅降级 |
改进
| 改进 | 描述 |
|---|
| SA5011 lint 合规 | 在 t.Fatal 后添加 return 并删除多余的 nil 检查 |
| 测试断言增强 | 用真实断言替换跨包的 no-op 测试 |
| 死代码清理 | 移除未使用的 CJK 回退、manifest 辅助函数、搜索变量 |
| 依赖更新 | fsnotify v1.10.1、chromedp/cdproto 刷新 |
| 文档完善 | 编写 ResolvePath 安全契约，合并 EvalSymlinksAncestor |
发布日期：2026-06-17
主题：正确性修复、macOS 安装体验改进、依赖刷新
修复问题
| 修复 | 说明 |
|---|
弃用的 navigator.platform | Mac 检测改用 navigator.userAgent，快捷键徽标在现代浏览器中正确显示 |
| SPA 搜索范围与 Escape 冲突 | 搜索辅助函数通过 window 全局暴露，SPA 导航后依然可用；搜索面板打开时侧边栏 Escape 处理加保护 |
| 灯箱焦点恢复 | 恢复焦点后清空过期引用 |
| 文件读取 TOCTOU 缺口 | EPUB 图片加载等 stat-then-read 模式改为原子读取 |
| git clone 超时与凭据挂起 | GIT_TERMINAL_PROMPT=0 加 WaitDelay 防止无限阻塞；克隆超时可配置 |
根目录 SubDir 包含性检查 | 与源根目录相同的子目录不再被误判为路径逃逸 |
改进
| 改进 | 说明 |
|---|
| Homebrew cask 自动去隔离 | post-install 钩子自动移除 macOS Gatekeeper 隔离属性 |
| Go 1.26.3 与依赖升级 | 标准库安全修复，以及 chroma、pflag、x/sys 等依赖刷新 |
| CI 升级 golangci-lint v2.12.2 | GitHub Actions 与 GitLab CI 对齐最新 linter |
| 扩充英文 CLI 手册 | 命令文档补充详细参数说明 |
发布日期：2026-07-05
主题：全项目审计 —— 安全、管线正确性、更安全的自升级
安全修复
| 修复 | 优先级 | 说明 |
|---|
| 远程插件执行门禁 | P0 | 远程项目的插件仅在传入新的 --allow-plugins 时才执行；本地项目不受影响 |
| GITHUB_TOKEN 泄露 | P0 | token 不再嵌入克隆 URL，也不会残留在临时克隆的 git 配置中 |
| 服务页面安全头 | P1 | 实时预览的 HTML 响应带上 X-Content-Type-Options、X-Frame-Options、CSP 等 |
| 插件信任模型文档化 | P2 | 手册明确说明 book.yaml 插件是任意可执行程序 |
缺陷修复
| 修复 | 说明 |
|---|
| 数学预处理破坏代码块 | $/$$ 替换跳过围栏代码与行内代码，shell/awk/PHP 示例不再被破坏 |
| Typst 后端正确性 | 合法的 font: 数组、通过 --root 解析图片路径、正文转义 $ # @ < > 与不成对的 */_ |
| EPUB 图片处理 | 共享的 ../images/... 资源可打包；非 base64 data URI 仅警告不再中止 |
| 实时服务健壮性 | 监听新建目录、串行化重建、WebSocket 保活、优雅退出 panic 修复 |
serve --branch/--subdir | 两个参数注册到 serve，支持远程分支/子目录预览 |
doctor 增强 | 新增 Typst 可用性检查；--strict 在错误级检查失败时非零退出 |
quickstart 目标处理 | 目标为文件时给出友好错误；--force 支持非空目录 |
| 版本上报 | 源码构建回退到 runtime/debug.ReadBuildInfo() |
改进
| 改进 | 说明 |
|---|
更安全的 upgrade | 尊重 Homebrew/go install 安装方式（--force 可覆盖）；校验和缺失直接失败（--skip-checksum 显式跳过） |
| 新 CLI 参数/缩写 | --allow-plugins（build/serve）、-o/-f 缩写、--strict（doctor）、--force/--skip-checksum（upgrade）、--force（quickstart） |
| Linux 安装包与源码归档 | Releases 新增 .deb/.rpm/.apk 安装包和带校验和的源码 tarball |
| 更快的 Docker 构建 | 构建阶段通过 $BUILDPLATFORM 交叉编译，无需 QEMU 模拟 |
| 文档准确性 | 移除不存在的参数示例、修正输出路径、恢复中英文手册对齐 |
发布日期：2026-07-05
主题：出版级默认外观与一致的站点输出目录
变更
| 变更 | 说明 |
|---|
重调 technical 主题 | 默认深海军蓝整版封面、精调的海军蓝墨色、层级化书籍目录、发丝级表格边框加着色表头与斑马纹、图片描边、行内代码浅色底、强调条引用块；标注块不再跨 PDF 分页 |
| 站点阅读栏居中 | 阅读栏居中显示，右侧页面目录为空时自动收起 |
build --format site 默认输出 _book/ | 与 mdpress serve 及部署示例保持一致；--output <dir> 可另行指定；多语言构建保留按语言的 <lang>_site/ 布局 |
发布日期：2026-07-10
主题：可预期的输出路径、真正的自定义主题机制、各格式渲染质量
变更
| 变更 | 说明 |
|---|
可预期的 --output 语义 | 目录目标接收文件并就地写入站点页面；文件基名目标生成 <base>.pdf/<base>_site/；默认站点先构建到临时目录再原子替换 _book/，带旧页面清理和对非生成目录的安全检查 |
| 远程构建输出 | 不带 --output 的远程 GitHub 构建把产物写入当前工作目录，而非临时目录 |
| 构建结果汇总 | 每种格式打印一行 ✓ Generated <format> → <path>，--quiet 下也会输出 |
| PDF 默认样式 | 居中页码页脚取代强制的 "Built with mdPress" 页脚；style.header/style.footer 生效并支持 {page}/{pages}/{title} 占位符；新增 output.tagged_pdf 开关，可换取更小的 PDF |
| 真正的自定义主题 | style.theme: mytheme.yaml 加载 YAML 主题文件；项目内 themes/<name>.yaml 覆盖或定义主题；themes list/show/preview 基于实际调色板输出 |
| 主题重调与主题感知封面 | elegant（暖色衬线、青铜强调色）与 minimal（安静单色）重调；未配置封面时默认封面跟随主题 |
| 站点改进 | 全相对链接（支持 GitHub Pages 项目站点和 file://）、output.site_url 生成 sitemap.xml、output.edit_base 生成逐章“编辑此页”链接、生成 404.html、修复深色模式表格与代码块 |
| 独立 HTML | 新增封面横幅区，修复深色模式 |
| EPUB 质量 | 章节标题作为 <h1> 呈现、主题派生的阅读器友好样式表、含数学章节声明 scripted remote-resources |
| Serve 监听修复 | 通过忽略生成产物目录，修复首次编辑后的无限重建循环 |
| 脚手架清理 | quickstart/init 不再硬编码封面背景色，也不再生成占位 cover.svg；自动生成 .gitignore；修正 shell 补全指引 |
发布日期：2026-07-22
主题：修复第二轮完整审计确认的问题，并为反复产生这些问题的模式补上守卫测试
变更
| 变更 | 说明 |
|---|
serve --output <dir> 不再具有破坏性 | 每次重建的目录替换会清空既有目录内容；serve 现在与 build --format site 一样，提前拒绝非生成目录 |
| 站点根目录权限 | 原子替换把 0700 的临时目录发布为站点根目录，在 nginx/httpd 下整站 403；现已改为所有人可读 |
| EPUB 正确性 | 布尔属性展开不再改写正文；同名章节不再互相覆盖；跨章 .md 链接会被重写；package/NCX/nav 中的引用做百分号编码 |
--format typst 能构建脚手架项目 | book.language 被原样传给 Typst 的 lang:（只接受 ISO 639 码），导致所有生成的项目都失败；现在会归一化 |
--format epub -o <newdir>/book.epub | EPUB 是唯一不会创建输出目录的后端 |
| 排版配置生效 | style.font_family / font_size / line_height 此前只有 Typst 后端读取；PDF、HTML 与站点现在同样生效 |
| 站点搜索排序 | 结果在排序之前就被截断为 20 条，标题命中的页面可能完全不出现；统计数也是截断后的 |
| 监听器处理删除与重命名 | 被删除的章节会一直继续提供，直到一次无关编辑触发重建 |
| 零配置语言检测 | DefaultConfig 硬编码 zh-CN，英文文档目录会构建出中文界面与封面 |
--format all 不再包含 typst | 在没有可选 Typst CLI 的机器上 all 会失败；如需备用 PDF 后端请显式使用 --format typst |
| 排版默认值下沉到主题 | 未设置的 style.* 现在表示「继承主题」。破坏性变更：未写 language: 的 book.yaml，除非内容以 CJK 为主，否则解析为 en-US |
| 守卫测试 | 跨格式矩阵 fixture、驱动真实 CLI 的样式串联测试，以及把 docs/ 中每条 mdpress … 调用解析到真实命令树的测试 |
发布日期: 2026-07-23
主题: 构建成功、输出看起来合理、作者却无从排查的那一类缺陷
变更
| 变更 | 说明 |
|---|
| 共享图片目录 |  在站点、单文件 HTML 和 PDF 中被丢弃且无任何提示；包含性检查针对章节所在目录而非书籍根目录 |
Front matter、BOM 与多余的 <h1> | YAML front matter 被当作正文渲染，UTF-8 BOM 使首个标题不再被识别为标题，第二个 <h1> 会导致页面标题消失 |
migrate 不再破坏文档 | 在已有围栏代码块外又加了一层围栏，就地吞掉文件其余内容，且没有备份 |
validate 可用作 CI 门禁 | 围栏代码块内的 Markdown 被当作真实引用（mdPress 自己的手册报出 92 个假错误）；新增 --strict、锚点检查、孤儿文件与重复章节检查 |
--config 生效 | 只要同时给出源目录，该参数就会被丢弃 |
未知的 book.yaml 键 | 报错并给出"是否想输入"建议，而不是静默丢弃 |
| PDF 输出 | output.margin_* 真正作用于 @page；目录有标题并通过两遍渲染填入真实页码；page-break-inside: avoid 不再制造大量近空白页 |
| ePub 输出 | 打包前解析每个文档，保留层级与代码高亮，并生成封面图 |
| 站点体积 | 图片以文件形式发布而非在每页内联 base64：含一张截图的 3 页书从 3.5 MB 降到 1.0 MB |
| 多语言布局 | 破坏性变更：--output 的各种写法现在都解析为同一棵可部署目录树，语言切换页位于其 index.html |
--format site --output ./dist | 破坏性变更：输出到 ./dist，不再在路径不存在时追加 _site |
| Ctrl+C 能中断构建 | SIGINT 被捕获却从未被响应，中断后仍留下看似正常的产物 |
| CDN 资源锁版本并校验完整性 | CDN 被屏蔽或被篡改时，向读者展示说明与图表源码，而不是一片空白 |
| PlantUML 文档回归事实 | mdPress 并不渲染它，但手册宣称自动渲染且 doctor 建议用户安装 |
| 新增命令 | config show、cache info/clear、validate --strict、version --json、static/ 透传、站点品牌、variables:、section: |
发布日期: 2026-07-23
主题: v0.8.0 自身的发布流程暴露出的两个缺陷
变更
| 变更 | 说明 |
|---|
| 已发布二进制报告自己的标签 | mdpress version 输出 0.8.0+dirty，之前的 0.7.15 同样如此：注入的标签只要与编译进去的默认值相同就会被丢弃，而每次规范发布这两者本来就相同，于是回退到 Go 的模块版本，该版本被 goreleaser 自己的构建前钩子标记为 dirty |
| Windows 章节路径 | 零配置发现写出 guide\README.md，而 init 与所有手写 book.yaml 写的都是 guide/README.md |
| Windows 测试覆盖 | 测试用的 CLI 二进制没有 .exe 后缀；图片包含性用例把 /etc/passwd 当作绝对路径 —— 在 Unix 上成立，在 Windows 上只是 rooted |
发布日期: 2026-07-24
主题: 第三次完整审计 —— 每个配置键都对着真实输出暴力验证、文档对着二进制做变异检查、PDF/ePub/站点逐字节检查 —— 外加对这批修复的复审
变更
| 变更 | 说明 |
|---|
mdpress upgrade 在 Linux 上可用 | 它下载了 .apk 包而非归档并装不上 —— 自 v0.7.12 起就不可用;现在选归档,并拒绝任何非目标平台可执行文件的载荷 |
build --format site 不再删 <output>.old | 原子替换拿这个同级名当暂存并提前删除 —— 正是用户的手动备份名;serve 甚至在安全检查前就删了 |
| PDF 目录 | 跨章节的重复标题互相拿错页码;两遍渲染现在像单文件 HTML 一样对锚点做命名空间隔离 |
build --format typst | 含代码块或跨行 emphasis 的书完全不出文件 —— 包括项目自己的手册,现在出 214 页 PDF |
| 数据丢失类修复 | CR-only 换行的章节整段静默丢失;含空格/查询串的链接与含 %20 的图片路径能解析;无法内嵌的图片会报告 |
| Ctrl+C 中断 PDF 构建 | 整个 40–90 秒渲染期间被忽略;退出时间从约 55 秒(且杀不掉)降到 0.1 秒,不留孤儿 Chrome |
| 页眉页脚不上封面 | Chrome 从打印参数逐页绘制,CSS 够不到第 1 页;现在删掉封面那行运行头,保留大纲与标签结构 |
| ePub | 空父级下仍保留目录;标题为 "Cover"/"Nav"/"Glossary" 的章节不再覆盖生成文件;术语链接指向 glossary.xhtml;id 合法 |
| 配置照写生效而非猜测 | defaults-as-sentinel 缺陷又查出五处(主题页面尺寸/边距、语言目录的 language、book.json 的 language/version、--config 路径写法);加载现在记录用户实际写了哪些键 |
| Windows 上找得到 Chrome | 搜索列表是 Unix-only,PDF 在原装 Windows 上从来无法工作 |
| 站点 | 深层嵌套章节被链接;引号短语与 CJK 搜索可用;暗色 h5/h6 对比度;共享 CSS/JS 把每页体积从约 110 KB 降到约 9 KB |
mdpress migrate | 解析 GitBook 的 {{ book.x }} 变量而非输出字面文本,并在报告中说明 |
| 发布安全 | make bump VERSION=x.y.z 替代九个手改文件;流水线现在下载已发布产物并断言其版本号等于 tag —— 连续两版漏掉 <tag>+dirty 的那个洞 |
| 文档与二进制一致 | 删掉不存在的键,修正过期默认值,并把 0.8.0 引入却从未在手册出现的功能补齐(双语) |
目标发布日期：2027-Q1
主题：生产就绪，长期支持
稳定化目标
| 目标 | 说明 |
|---|
| API 稳定性 | CLI 参数和 book.yaml 配置格式冻结，遵循语义化版本 |
| 测试覆盖率 | 核心包测试覆盖率 ≥ 90% |
| 文档完备 | 完整的用户手册（中英双语）、API 文档、迁移指南 |
| 性能基准 | 建立性能基准测试套件，确保版本间无性能退化 |
| 平台验证 | macOS、Linux、Windows 全平台 CI 验证 |
| 安全审计 | 依赖安全扫描，确保无已知漏洞 |
计划功能
| 功能 | 说明 |
|---|
| 官方主题仓库 | 社区可贡献和分发主题 |
| 官方插件仓库 | 社区可贡献和分发插件 |
| 迁移工具 | 从 mdBook 的自动迁移脚本（GitBook/HonKit 迁移已通过 mdpress migrate 提供） |
v1.0.0 将作为第一个 LTS 版本，承诺：
- 至少 12 个月的 bug 修复支持
- 至少 18 个月的安全补丁支持
- 配置文件格式向后兼容
- CLI 参数向后兼容
以下功能在 v1.0.0 之后根据社区反馈优先级排列：
| 功能 | 说明 |
|---|
| GUI 编辑器 | 基于 Web 的可视化编辑器，所见即所得 |
| 云端构建服务 | SaaS 版本，推送 Git 仓库自动构建 |
| 协作编辑 | 多人实时协作编辑（类 Google Docs） |
| PDF/A 归档格式 | 支持 PDF/A 标准，适合长期存档 |
| 印刷输出优化 | 出血线、色彩管理、ICC profile 支持 |
| DOCX 输出 | 生成 Word 文档格式 |
| 模板市场 | 书籍模板市场，提供预设的设计和排版方案 |
如何参与
mdpress 是开源项目，欢迎社区贡献：
- 报告问题：在 GitHub Issues 中提交 bug 报告
- 功能建议：在 Issues 中提交 Feature Request，标注希望的版本
- 代码贡献：Fork 仓库，提交 Pull Request（请先阅读 CONTRIBUTING.md）
- 文档改进：帮助完善文档和翻译
- 主题贡献：设计和分享自定义主题
路线图会根据社区反馈和实际进展持续调整。最新版本请查看本文档。