295 lines
11 KiB
Markdown
295 lines
11 KiB
Markdown
# Markdown PDF 导出器进度
|
||
|
||
最后更新：2026-07-25
|
||
|
||
## 1. 当前概况
|
||
|
||
项目目录：
|
||
|
||
```text
|
||
C:\Projects\md-to-pdf
|
||
```
|
||
|
||
当前分支：
|
||
|
||
```text
|
||
main
|
||
```
|
||
|
||
已有提交：
|
||
|
||
```text
|
||
ec14f79 feat: 扩展本地主题兼容能力
|
||
fa07472 feat: 实现网页实时预览
|
||
7224dfd feat: 实现 Markdown 渲染核心
|
||
ec48bce chore: 初始化项目骨架
|
||
```
|
||
|
||
当前工作区存在未提交修改，主要是导出配置版本 2、导出设置抽屉、浏览器缓存和实时纸张尺寸及页边距预览。接手时必须保留并审查这些修改，不要重置工作区。
|
||
|
||
## 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 项。
|
||
|
||
## 3. 当前未提交工作
|
||
|
||
以下内容已写入工作区，但尚未提交：
|
||
|
||
### 3.1 导出配置版本 2
|
||
|
||
- 纸张只保留 A3、A4、A5、US-Letter 和 US-Legal。
|
||
- 固定纸张尺寸分别为 297×420、210×297、148×210、216×279 和 216×356mm。
|
||
- 默认 A4 纵向，四边页边距均为 16mm。
|
||
- 统一采用 96 CSS px/in、72 PDF pt/in 和 25.4mm/in 的物理单位换算。
|
||
- 保留横向和纵向。
|
||
- 页脚模型收敛为页码设置，支持五种页码样式、对齐和起始页码。
|
||
- 校验页边距之和必须为正文保留正尺寸区域。
|
||
- 增加 6 项共享配置测试。
|
||
|
||
### 3.2 导出设置和浏览器缓存
|
||
|
||
- 增加响应式右侧导出设置抽屉。
|
||
- 支持五种纸张、方向和四边页边距。
|
||
- 已提供页眉左中右内容、页脚页码样式、位置、起始页码和分隔线控件。
|
||
- 配置和主题选择写入版本化 `localStorage`，不缓存 Markdown 正文。
|
||
- 缓存缺失、损坏或版本过期时恢复默认配置。
|
||
- 切换到更小纸张时自动等比例收敛过大的旧页边距。
|
||
- 增加 3 项浏览器缓存测试和 3 项打印媒体预览测试。
|
||
|
||
### 3.3 实时纸张预览
|
||
|
||
- 纸张尺寸、方向和四边页边距实时作用于预览。
|
||
- 删除本地主题专用的 8mm 外边距特例。
|
||
- 在主题 CSS 后追加共享几何 CSS，统一清除 `body` 和 `#write` 的页面宽度、内外边距限制。
|
||
- 网页预览将主题的 `@media print` 规则按原始位置转换为屏幕预览规则，使 Typora GitHub 等主题使用与 PDF 相同的打印字号和行高。
|
||
- 固定逻辑页面后续按 96 CSS px/in 分页，预览显示倍率只缩放外层，不参与正文换行和分页计算。
|
||
- 页眉和页码配置将在下一阶段分页预览中显示。
|
||
|
||
### 3.4 Mermaid 配置与错误隔离
|
||
|
||
- 使用 Mermaid 官方 npm 包，当前锁定安装版本为 11.16.0。
|
||
- 无区块配置时显式使用 `default` 主题和 `classic` 外观。
|
||
- Mermaid 区块内容原样交给官方解析器，支持区块内部的 YAML `config` frontmatter。
|
||
- 允许区块覆盖主题、外观、主题变量、布局及图表专属配置。
|
||
- 固定 `strict` 安全级别、自动启动开关、文本和边数量限制、错误输出策略，并禁止区块注入原始 `themeCSS`。
|
||
- 单个 Mermaid 图表解析或渲染失败时显示局部错误，其余图表继续渲染。
|
||
- 增加 Mermaid 站点配置、单图错误隔离及区块 frontmatter 保留测试。
|
||
|
||
## 4. 已执行验证
|
||
|
||
2026-07-25 在当前完整工作区成功执行：
|
||
|
||
```text
|
||
npm test
|
||
npm run typecheck
|
||
npm run build
|
||
git diff --check
|
||
```
|
||
|
||
结果：
|
||
|
||
- 共享配置测试：6 项通过；
|
||
- 渲染器测试：6 项通过；
|
||
- 前端测试：10 项通过；
|
||
- 后端测试：6 项通过；
|
||
- 全项目类型检查通过；
|
||
- 生产构建通过；
|
||
- `git diff --check` 通过，仅出现工作区 LF 将来可能转为 CRLF 的提示；
|
||
- 导入器默认的已存在目标保护通过；
|
||
- GitHub、Pixyll 和 Whitey 三套本地主题的 CSS API 均返回成功，组合结果无残留 `@import`。
|
||
|
||
已使用浏览器插件完成视觉验证：
|
||
|
||
- 导出设置抽屉桌面布局正常；
|
||
- 尺寸选择器只包含五种目标纸张；
|
||
- 默认 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` 是当前预览实现的主要文件。
|
||
- `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. 推荐接手顺序
|
||
|
||
### 阶段一：完成分页预览
|
||
|
||
导出设置、缓存和实时纸张几何已经完成。下一步按已确认设计引入 Paged.js，并实现：
|
||
|
||
- 逐页预览；
|
||
- 页眉左中右内容及变量替换；
|
||
- 页脚页码、总页数、对齐和起始页码；
|
||
- Mermaid 整体换页和超高图按页面正文高度等比例缩放；
|
||
- 字体、图片和 Mermaid 完成后再分页；
|
||
- 预览与未来 PDF 共用分页 HTML 和 CSS。
|
||
|
||
### 阶段二：实现真实 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 可在内网启动。
|