PDF Generator

本项目是一个本地离线可用的 Markdown 转 PDF 桌面软件，面向 Windows 使用场景，重点解决下面几类常见问题：

• 本地图片在网页转换器里经常无法正确加载
• Markdown 预览正常，但导出 PDF 后排版走样
• 需要通过 CSS 自定义论文、实验报告、课程作业等版式
• 需要在应用里直接编辑 Markdown，而不是反复切换编辑器
• 数学公式、Mermaid、代码块、表格在分页导出时容易出错

当前技术栈：

• Electron
• React
• TypeScript
• Vite

主要功能

1. 本地 Markdown 导入与编辑

• 支持打开 .md / .markdown 文件
• 支持拖拽 Markdown 文件到界面中直接导入
• 支持在程序内直接编辑 Markdown
• 支持保存当前 Markdown 内容回原文件或新文件

2. 本地图片路径稳定解析

应用会以 Markdown 文件的真实路径为基准解析资源，尽可能兼容常见编辑器与写法，重点支持：

• 相对路径图片
  • ![img](./images/a.png)
  • ![img](../assets/a.png)
• Windows 绝对路径图片
  • ![img](C:\docs\img\a.png)
  • ![img](<C:\docs\img\figure 1.png>)
• file:/// 本地文件 URL
• HTML 图片
  • <img src="./images/a.png" />
• Obsidian 图片嵌入
  • ![[image.png]]
  • ![[image.png|320]]
• Typora / Obsidian 常见本地图片写法

如果资源不存在，应用不会崩溃，而是给出明确警告并继续预览、继续导出。

3. 预览与 PDF 导出一致

• 预览与导出共用同一套渲染模板
• 支持分页预览
• 预览区可以看到接近最终 PDF 的页面效果
• 导出时会内联本地图片，减少 PDF 中图片丢失问题

4. CSS 样式定制

支持两层样式能力：

• 可视化样式面板
• 高级 CSS 直接编辑

可视化面板可调整：

• 纸张大小
• 方向
• 页边距
• 正文宽度
• 字体族
• 正文字号
• 行高
• 段落间距
• 标题缩放
• 代码字号
• 代码主题
• 表格紧凑模式
• 图片宽度策略
• 是否打印背景
• 页眉开关与文本
• 页脚开关与文本

高级 CSS 支持直接覆盖默认样式，适合自定义学校实验报告、课程论文、技术报告等格式。

5. 样式方案导入导出

• 支持导出样式方案文件
• 支持重新导入样式方案恢复界面状态
• 导出的内容同时包含：
  • 可视化控件值
  • 原始高级 CSS

6. 分页控制

支持分页预览，并允许用户控制以下元素在跨页时的行为：

• 代码块是否允许分页切分
• 表格是否允许分页切分
• 引用块是否允许分页切分
• 图片是否允许分页切分

这对于长代码块、长表格、实验报告截图等内容尤其重要。

7. 数学公式支持

当前版本已经将数学公式渲染链路切换为更稳定的 SVG 输出，避免浏览器打印引擎对公式做二次错误排版。

支持：

• 行内公式
• 块级公式
• 上标 / 下标
• 积分、极限、分式
• 矩阵
• 分段函数
• 常见 LaTeX 数学写法

当前实现特点：

• 公式预览与 PDF 导出一致
• 所有公式字号与正文字号绑定
• 不再出现导出后上标跑偏、矩阵错位、指数掉到右下角等问题

8. Mermaid 流程图支持

• 支持 Mermaid 代码块渲染
• 支持在预览与导出中保留流程图效果
• 对渲染失败的 Mermaid 内容提供回退展示

9. 实验报告风格模板

项目内置了一套偏“实验报告 / 课程作业 / 技术文档”的 CSS 模板，适合中文排版。

模板位置：

• experiment-report.css

风格特点：

• 标题层级清晰
• 正文更适合中文长段落阅读
• 表格、代码块、图片边框更稳重
• 更接近纸质实验报告的视觉气质

界面说明

应用采用三段式桌面布局：

• 顶部工具栏
  • 打开文件
  • 保存 Markdown
  • 重新加载
  • 导入样式
  • 导出样式
  • 生成 PDF
• 左侧控制区
  • 文件拖拽导入
  • Markdown 编辑器
  • 样式面板
  • 高级 CSS 编辑器
• 右侧预览区
  • 状态提示
  • 图片警告数量
  • 当前页面规格信息
  • 分页预览

使用说明

基本流程

1. 启动程序。
2. 点击“打开文件”，或者直接把 Markdown 文件拖进左侧拖拽区域。
3. 程序会自动读取 Markdown，并按 Markdown 文件所在目录解析本地图片。
4. 如有需要，可以直接在左侧 Markdown 编辑区修改内容。
5. 在样式面板中调整页面、字体、代码块、表格、图片、页眉、页脚等设置。
6. 如果需要更深度定制，可直接修改高级 CSS。
7. 在右侧确认分页预览效果。
8. 点击“生成 PDF”，选择保存位置后导出。

适合的使用场景

• 软件安全实验报告
• 课程作业
• 技术说明文档
• 论文草稿
• 学习笔记整理
• Obsidian / Typora 文档导出

开发与运行

环境要求

• Windows
• Node.js 24+
• npm 11+

已验证环境：

• node v24.14.0
• npm 11.9.0

安装依赖

npm install

启动桌面应用

npm run build
npm start

运行测试

npm test

构建前端与主进程

npm run build

生成 Windows release 目录

推荐使用 win-unpacked 目录形式进行本地分发和测试：

npx electron-builder --win --dir

生成后的可执行文件位置：

• dist/win-unpacked/PDF Generator.exe

生成安装包

如果本机相关依赖完整，也可以尝试：

npm run package

Electron 依赖下载异常时

如果 Electron 下载失败，可以重试：

npm run repair:electron

测试覆盖

当前项目已经覆盖了多类核心回归测试，包括：

• 相对路径图片解析
• 缺失图片告警
• URL 编码后的 Windows 绝对路径恢复
• Markdown / HTML 图片统一处理
• Obsidian 图片嵌入解析
• 扁平化代码段恢复为代码块
• 数学公式输出为稳定 SVG
• PDF 导出前本地图片内联