MorphDoc/docs/PROGRESS.md

Markdown PDF 导出器进度

最后更新：2026-07-26

1. 当前概况

项目目录：

C:\Projects\md-to-pdf

当前分支：

main

已有提交：

52cf816 feat: 完善导出设置与打印预览
ec14f79 feat: 扩展本地主题兼容能力
fa07472 feat: 实现网页实时预览
7224dfd feat: 实现 Markdown 渲染核心
ec48bce chore: 初始化项目骨架

当前工作区存在未提交修改，主要是基于 Paged.js 的真实分页预览、页眉页码、跨页表格和超高 Mermaid 图表适配。接手时必须保留并审查这些修改，不要重置工作区。

2. 已完成

2.1 项目骨架

• 建立 npm workspaces。
• 建立 React + Vite 前端。
• 建立 Fastify 后端。
• 建立 packages/core 共享包。
• 建立主题、测试和 Docker 目录。
• 初始化本地 Git 仓库。

2.2 导出配置模型

packages/core/src/export-config.ts 已包含：

• 配置版本号；
• A3、A4、A5、Letter、Legal、Tabloid 和自定义纸张；
• 横向、纵向；
• 四边页边距；
• 页眉和页脚左右中区域；
• 页码位置和格式；
• PDF 元数据；
• 打印背景、缩放和一级标题分页选项；
• Zod 数据校验；
• 默认 A4 技术文档预设。

2.3 主题接口

packages/core/src/theme.ts、themes/typora-like 和动态主题注册器已包含：

• 版本化主题清单；
• 主题 ID、名称、版本、作者、许可证；
• DOM 预设；
• 支持能力声明；
• 可选基础 CSS、主体 CSS 和打印 CSS；
• 自制 Typora 风格主题；
• #write 兼容文档结构；
• 内置主题和 .local/themes 本地主题动态扫描；
• 按基础 CSS、主体 CSS、打印 CSS 的固定顺序组合；
• 主题内相对 CSS @import 安全展开；
• 主题 CSS 相对资源重写与受限资源接口；
• 目录匹配、真实路径包含关系和外部 URL 安全检查。

内置主题为项目自有实现，没有复制 Typora 官方默认主题。用户可以通过导入工具将本机已安装的 Typora 基础 CSS以及 GitHub、Pixyll 和 Whitey 三套适合打印的白色默认主题复制到 Git 忽略的 .local/themes。这些副本仅供本机使用，不进入仓库、容器或发布包。

2.4 Markdown 渲染核心

提交 7224dfd 已完成：

• packages/renderer 独立工作区；
• Front Matter 解析；
• Markdown 到安全 HTML；
• 标题锚点；
• 表格；
• 任务列表；
• 脚注；
• highlight.js 代码高亮；
• KaTeX 数学公式；
• Mermaid 安全占位；
• sanitize-html 安全过滤；
• 元数据规范化；
• 功能检测；
• 统一 <article id="write"> 输出；
• 5 项渲染单元测试。

2.5 网页实时预览

提交 fa07472 已完成：

• 可测试的 Fastify buildApp()；
• POST /api/render 服务端统一 Markdown 渲染；
• 动态主题清单、CSS 和资源 API；
• Markdown 编辑及本地 .md 文件读取；
• 250ms 防抖 A4 实时预览；
• iframe 隔离主题 CSS；
• KaTeX、highlight.js 和按需加载的 Mermaid；
• 桌面双栏与移动端上下布局；
• 5 项渲染器测试和 4 项后端测试。

2.6 主题兼容增强

提交 ec14f79 已完成：

• 主题清单可选基础 CSS；
• 基础 CSS、主体 CSS、打印 CSS 固定组合顺序；
• 安全的相对 CSS @import 展开和资源 URL 重写；
• CSS 导入深度、循环、外部 URL 和越界路径检查；
• GitHub、Pixyll 和 Whitey 三套本地 Typora 白色主题导入；
• 可恢复替换和默认防覆盖；
• 主题开发指南；
• 后端测试增至 6 项。

2.7 导出设置与打印预览

提交 52cf816 已完成：

• 导出配置升级到版本 2；
• 纸张收敛为 A3、A4、A5、US-Letter 和 US-Legal；
• 默认 A4 纵向和 16mm 四边页边距；
• 统一 96 CSS px/in、72 PDF pt/in 和 25.4mm/in 的物理单位换算；
• 响应式导出设置抽屉；
• 纸张、方向、页边距、页眉、页码和主题的版本化浏览器缓存；
• 页眉左中右内容和变量；
• 五种页码样式、对齐和起始页码；
• Mermaid 官方配置 frontmatter、默认主题与错误隔离；
• Markdown 表格对齐属性保留和自适应列宽；
• 纸张尺寸和页边距实时预览。

3. 当前未提交工作

以下内容已写入工作区，但尚未提交：

3.1 Paged.js 真实分页预览

• 引入 MIT 许可证的 Paged.js 0.4.3。
• 使用独立同源沙箱 iframe 执行分页，父页面通过严格消息协议传递渲染载荷。
• 每张纸以真实物理尺寸独立显示，页面间保留 24px 间隔和预览阴影。
• 主题 CSS 原样交给 Paged.js，使主题 @media print 规则与未来 PDF 一致。
• GitHub 主题打印字号已与 Typora PDF 对齐：正文 13px、一级标题 29.25px、二级标题 22.75px。
• W30 对照文档在 Typora 和网页预览中均为 4 页。
• 主题切换会重置 iframe 就绪握手，GitHub、Pixyll 和 Whitey 可连续切换且无需刷新。

3.2 页眉、页码与跨页内容

• 页眉支持左中右三栏、标题、作者和文件名变量及分隔线。
• 页脚支持五种页码格式、左中右位置、起始页码和分隔线。
• 当前页码逐页递增，总页数使用真实分页结果。
• 标题避免孤立在页尾，段落使用孤行和寡行约束。
• 长表格允许跨页，并通过 Paged.js 处理器重复表头。
• 表格行、代码块、引用、公式、图片和 Mermaid 默认避免从中间断开。

3.3 Mermaid 单页适配

• Mermaid、字体和图片完成后再启动分页。
• 普通 Mermaid 保持主题原有尺寸和布局。
• 根据纸张和页边距计算正文区域的 CSS 像素宽高。
• 当 SVG 按正文宽度适配后仍高于一页时，读取 viewBox 并改为按正文高度等比例缩小。
• 超高 Mermaid 整体换页、水平居中，不跨页裁切。
• 浏览器实测 A4 超高图高度约 1000.56px，正文可用高度约 1001.57px，未侵入上下页边距。
• 增加 SVG viewBox 解析、正文尺寸和缩放算法测试。

4. 已执行验证

2026-07-26 在当前完整工作区成功执行：

npm test
npm run typecheck
npm run build
git diff --check

结果：

• 共享配置测试：6 项通过；
• 渲染器测试：7 项通过；
• 前端测试：21 项通过；
• 后端测试：6 项通过；
• 全项目类型检查通过；
• 生产构建通过；
• git diff --check 通过，仅出现工作区 LF 将来可能转为 CRLF 的提示；
• 导入器默认的已存在目标保护通过；
• GitHub、Pixyll 和 Whitey 三套本地主题的 CSS API 均返回成功，组合结果无残留 @import。
• 同一份 W30 Markdown 在 GitHub 分页预览和 Typora PDF 中均为 4 页。
• 三个本地主题无需刷新即可连续切换并重新分页。
• 超高 Mermaid 整体缩放到单页正文区域，普通 Mermaid 尺寸不受影响。

已使用浏览器插件完成视觉验证：

• 导出设置抽屉桌面布局正常；
• 尺寸选择器只包含五种目标纸张；
• 默认 A4 纵向及 16mm 四边距正确；
• A5 横向和 12.5mm 上边距实时反映到纸张；
• GitHub 主题的 #write 宽度、最大宽度、内外边距已由共享几何层接管；
• 刷新页面后纸张、方向、页边距、页眉和页码配置可以恢复；
• 恢复默认功能正常；
• 浏览器控制台无警告或错误。

此前主题阶段已使用浏览器插件完成视觉验证：

• 导入并打开 tmp/数据中台项目周报_2026_W30.md；
• 参考 tmp/数据中台项目周报_2026_W30.pdf 的 Typora 输出；
• GitHub、Pixyll 和 Whitey 三套保留的本地主题均可正常切换；
• 三套主题中的表格均为 border-collapse: collapse、单元格间距为 0，并铺满 #write 内容宽度；
• GitHub 表格边框颜色与主题定义的 #dfe2e5 一致；
• Open Sans、PT Serif 和 Merriweather 字体资源均成功加载；
• KaTeX、代码高亮和 Mermaid 正常显示；
• 浏览器控制台无警告或错误。

为方便用户继续检查，开发服务当前仍在后台运行，前端监听 5173，后端监听 3001。

5. 当前注意事项

• 工作区不是干净状态，禁止重置。
• apps/web/src/App.tsx 负责分页 iframe 生命周期和父页面消息处理。
• apps/web/src/paged-preview-frame.ts 负责 iframe 内 Mermaid、资源等待和 Paged.js 分页。
• apps/web/src/paged-preview.ts 负责分页协议、共享文档 CSS、页眉和页码 CSS。
• apps/web/src/mermaid-page-fit.ts 负责超高 Mermaid 的单页等比例适配。
• apps/web/src/paged-table-handler.ts 负责跨页表格表头处理。
• apps/web/src/ExportSettingsDrawer.tsx 是导出设置界面。
• apps/web/src/export-settings.ts 负责版本化浏览器缓存。
• packages/core/src/export-config.ts 是纸张、页边距、页眉页脚和页码的共享模型。
• apps/server/src/app.ts 是新增的可测试 Fastify 应用。
• apps/server/src/theme-registry.ts 负责内置和本地主题发现、CSS 处理及资源安全。
• .local/themes/typora-* 是用户本机副本，已被 Git 忽略，不得提交。
• .local/theme-backups 中保留 GitHub、Pixyll 和 Whitey 的可恢复备份；Newsprint 和 Night 的当前副本及备份已按用户要求删除。
• Typora 官方资源是 All Rights Reserved，仅限当前用户本机使用，不进入 Git、容器或发布包。
• Mermaid 已按需加载，但生产构建仍提示 mermaid.core 和 cynefin 两个分块超过 500 kB；这不影响功能，可后续优化。
• PDF 生成尚未实现。
• 资源目录上传、本地相对图片、临时目录和路径安全尚未实现。
• Dockerfile 和 Compose 尚未实现。

6. 推荐接手顺序

阶段一：提交分页预览

当前分页预览已经实现并通过验证。检查完整差异并创建一个清晰的阶段提交后，再进入真实 PDF。

阶段二：实现真实 PDF

分页预览提交后再实现：

1. 增加 Playwright 和固定版本 Chromium。
2. 抽取可复用的完整 HTML 文档组装器。
3. 预览和 PDF 共用文章 HTML、主题 CSS、打印 CSS及资源。
4. 等待字体、图片、KaTeX 和 Mermaid 完成。
5. 实现 POST /api/pdf，响应 application/pdf。
6. 前端启用“导出 PDF”按钮并下载文件。
7. 增加 PDF 接口与端到端测试。

阶段三：导出配置扩展

• Front Matter 元数据覆盖；
• 浏览器本地配置预设；
• 配置 JSON 导入和导出。

阶段四：资源与安全

• Markdown 文件夹或 ZIP；
• 相对图片解析；
• 每请求独立临时目录；
• 路径穿越防护；
• 文件数量、大小和超时限制；
• Chromium 并发和网络访问限制；
• 请求结束可靠清理。

阶段五：容器化与交付

• Dockerfile；
• Docker Compose；
• Chromium 字体与中文字体；
• 非 root 用户；
• 健康检查；
• 临时目录容量限制；
• 内网部署说明；
• 完整 PDF 样例和视觉回归验证。

7. 首版验收目标

• 可以选择或粘贴 Markdown；
• 网页正确预览常用 Markdown、公式和 Mermaid；
• 可以下载真实 PDF；
• PDF 文本可搜索；
• 预览与 PDF 基本一致；
• 支持 A4、Letter、方向和边距；
• 支持基础页眉、页脚和页码；
• 支持主题切换扩展；
• 相对图片可用；
• 转换后不保留用户文档；
• Docker Compose 可在内网启动。