# Markdown PDF 导出器

一个面向内网部署的 Markdown 排版与 PDF 导出工具。项目目标是使用同一份 HTML 和 CSS 完成网页预览与 Chromium PDF 渲染，并提供纸张、页边距、页眉页脚、页码及主题扩展能力。

## 当前状态

已经实现：

- React Markdown 编辑与本地文件读取；
- Fastify 预览接口；
- 共享导出配置模型；
- 动态主题清单、CSS 和静态资源接口；
- Markdown、Front Matter、安全过滤和扩展语法渲染核心；
- 表格、任务列表、脚注、代码高亮、KaTeX 和 Mermaid；
- iframe 隔离的真实分页预览、双向滚动同步与主题切换；
- 五种纸张、页边距、页眉、页码和浏览器配置缓存；
- 内置 Typora 风格主题，以及仅供本机使用的三套白色 Typora 默认主题导入工具；
- Docker 与 PDF 渲染目录预留。

Chromium PDF 下载和本地资源文件处理将在后续阶段实现。

## 本地开发

要求 Node.js 22 或更高版本。

```powershell
npm install
npm run dev
```

默认地址：

- 前端：http://localhost:5173
- 后端：http://localhost:3001
- 健康检查：http://localhost:3001/api/health

页面支持直接编辑 Markdown，或选择本地 `.md` 文件。文件内容将读取到当前浏览器页面并发送给内网转换服务，不写入数据库。

编辑区和分页预览使用双向比例滚动同步。在任意一侧滚动时，另一侧会跟随到相同的全文阅读进度，方便定位并修改较长文档。

## Mermaid 长标签

流程图节点标签的默认最大宽度为 320px。单个 Mermaid 区块可以通过 config frontmatter 覆盖：

````markdown
```mermaid
---
config:
  flowchart:
    wrappingWidth: 360
---
flowchart TB
  A["较长的节点名称<br/>第二行说明"] --> B["下一个节点"]
```
````

需要自动换行时可以使用 Mermaid Markdown String：

````markdown
```mermaid
flowchart LR
  A["`这是一段可以由 Mermaid 自动换行的较长节点文字`"]
```
````

个别节点仍需缩小字体时，优先使用 Mermaid 自带的 `classDef`：

````markdown
```mermaid
flowchart LR
  A["较长节点"] --> B["普通节点"]
  classDef compact font-size:12px;
  class A compact;
```
````

## 本地导入 Typora 默认主题

项目不会打包或提交 Typora 官方默认主题。如本机已安装 Typora，可以将 GitHub、Pixyll 和 Whitey 三套适合打印的白色默认主题及 Typora 基础 CSS 复制到 Git 忽略的本地主题目录：

```powershell
npm run theme:import-typora
```

默认从 Typora 安装目录的 `resources\style` 读取基础 CSS、主题和资源，写入 `.local\themes\typora-*`。启动开发服务后，这些主题会出现在预览页面的主题选择器中。

导入工具不会默认覆盖已存在的目标。确认替换本地副本时使用：

```powershell
npm run theme:import-typora -- --replace
```

旧副本会移动到 `.local\theme-backups`。

本地主题由动态主题注册器加载，CSS 中的相对字体和图片会通过受限资源接口提供。外部 URL、越界路径和符号链接逃逸会被拒绝。

自定义主题目录、`theme.json`、CSS 组合顺序、资源引用和安全限制详见 [主题开发指南](docs/THEMES.md)。

## 测试与构建

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

## 隐私原则

文档和资源文件仅用于当前转换请求。PDF 阶段将为每次请求创建隔离的临时目录，并在成功或失败后统一清理，不接入数据库或文档历史存储。