浏览器端纯本地 Markdown 转 PDF：数据隐私与网络边界说明

“在您的浏览器中完全本地运行”是一项实用的安全特性，但它并不能等同于免除所有网络请求。浏览器可以在不上传文件的情况下读取本地 Markdown，但当文档被渲染预览时，它同样可能会自动向第三方服务器请求加载远程图片。

md2pdf 是一个没有任何应用后端的纯静态网站。Markdown 语法解析、XSS 安全清洗、目录自动生成、排版预览、打印控制以及多文件图书排版均在访问者的终端设备上执行。这彻底免除了传统云端转换工具所必须的文件上传步骤，但并不意味着所有网络交互都会凭空消失。本指南将明确界定这一安全边界。

转换完整流程请参阅如何将 GitHub README 转换为 PDF。若需整合多文件制书，请参阅构建多文件 Markdown 图书并导出 PDF。

此处“纯浏览器本地”的具体定义

在 md2pdf 中，纯浏览器本地意味着产品中完全没有服务端渲染引擎。整个网站由纯静态 HTML、CSS 和 JavaScript 构成。当您粘贴 Markdown 时，文字仅存在于当前浏览器标签页的内存中；当您上传文件时，浏览器通过 File API 进行本地读取，文件绝不会被 POST 发送到任何远程端点。

但这并不代表页面始终处于离线状态。初次加载页面需要下载前端资源，从 GitHub 导入文档时也会向 GitHub API 发送合法的公开网络请求。

我们的承诺严谨且真实：您的 Markdown 文本绝不会被上传至 LadeStack，本工具不设用户账户，也没有任何服务端文档数据库。

端到端转换流水线详解

单篇文档在浏览器内部按以下阶段顺序流转：

source  ->  parse  ->  resolve  ->  render  ->  sanitize  ->  preview  ->  print

1. 读取源文档。 获取粘贴的文本、本地文件或从 GitHub 获取的公开 README。
2. 语法解析。 由 markdown-it 解析表格、任务列表、删除线和围栏代码等 GFM 语法。
3. 路径重写。 针对仓库来源，将相对图片路径改写为 raw.githubusercontent.com，相对链接改写为 GitHub 网页。
4. 生成 HTML。 将语法标记编译为基础 HTML 结构。
5. 安全净化。 DOMPurify 彻底剔除潜在的危险元素（脚本、样式、iframe 等）。
6. 页面预览。 将安全净化后的 HTML 注入页面，补全标题锚点并生成可选目录。
7. 最终输出。 调用浏览器系统打印引擎输出 PDF，或由 pdf-lib 组装打包为 ZIP。

除最初的源文档读取外，后续所有阶段均在您的设备本地完成。

哪些数据会离开浏览器

对于本地文件或粘贴的 Markdown，md2pdf 本身不会向外发送任何文档内容，因为网站根本没有接收文档的 API 接口。

日常使用中正常的网络通信包括：

• 静态站点资源。 从主机拉取网页所需的 HTML、CSS、JS 脚本及字体文件。
• GitHub 公开读取。 向 GitHub API 发送匿名请求，获取指定公开仓库的默认分支与 README 文件。
• Markdown 中的远程外链图片。 若文档引用了存放在其他服务器上的图片，浏览器在渲染预览时必须向该服务器发起图片下载请求。

例如，若文档中包含 ![dashboard](https://internal.example.test/chart.png)，尽管文本是本地的，但图片下载请求仍会发往目标主机。

普通超链接在读者主动点击前不会发起请求，但图片等嵌入媒体会在渲染时自动下载。

本地文件与粘贴板工作流

本地工作流具备最高级别的隐私保障：

• 粘贴文本。 除非 Markdown 自身包含外部图片链接，否则内容绝不脱离当前标签页。
• 本地上传。 严格在 2 MB 限制内由浏览器内存读取，绝不上演文件上传。
• 示例载入。 示例内容内置于静态资源包中，无需额外发起数据请求。

在粘贴或上传模式下，以相对路径引用的本地图片将无法显示，因为缺少仓库基准路径。请使用绝对 URL 或接受图片占位符提示。

如需绝对安全的离线导出，请在打印前移除文档中的外链图片。

远程图片与超链接依然属于网络请求

本地处理能够切实保护您的文档文本不被泄露，但它无法替您拦截文档所主动引用的外部资源。

请看以下典型示例：

![Architecture](./docs/architecture.png)

See the [operations guide](https://example.test/ops).

从 GitHub 导入时，图片路径会被自动重定向至 GitHub 原生托管源；而在粘贴模式下，绝对路径图片将直接由浏览器向目标源站索取。

在导出敏感文档前，建议在源代码中全文搜索核查：

• 以 http:// 和 https:// 开头的图片地址
• 原生 HTML <img> 标签
• 外链样式表或远程字体
• 内联 Base64 Data URI 图片（虽体积较大但不会产生外部网络通信）

DOMPurify 会坚决剔除脚本与危险标签，但会保留正常的图像，因为图像属于文档不可分割的内容。

GitHub 抓取上限与容错机制

GitHub 导入仅支持公开内容的非鉴权只读访问，具有严格的安全边界：

• API 单次请求超时时间为 15 秒。
• 章节内容抓取超时时间为 20 秒。
• 仓库目录结构扫描预算为 25 秒。
• 遭遇 API 频率受限时，支持自动回退至 Raw 原始内容抓取。
• 外链图片失效时会自动替换为占位图标，而绝不中断整体文档导出。

实用的文档隐私检查清单

在将内部或保密 Markdown 转换为 PDF 前，请快速自检：

• 文档中未包含指向内部受保护系统的私有图片链接。
• 检查公开仓库地址无误，未包含私密凭据。
• 文档正文中没有硬编码的密钥、密码或私有 Token。
• 在呼出系统打印对话框前已完整查验预览效果。
• 已确认全程未依赖第三方云端格式转换接口。

更多关于打印外观主题的配置建议，请参考 Clean、Business、Academic 与 Dark 主题解析。