# dsh-md-export

> English: [README.md](README.md)

DSH（DeepSeek Harness）Web 插件 —— **dsh-better-sidebar Markdown 导出扩展**。

在 better-sidebar 的 Markdown 文件预览器工具栏上新增一个**「导出」**按钮，点击后出现下拉菜单，可选择：

- 📄 **保存 HTML（同目录）** —— 把当前 `.md` 文件渲染为独立 `.html` **直接保存到 md 文件同目录**（Markdown 表格 / 代码块 / **Mermaid 图表**均已渲染内联，页面布局跟随原 md 预览主题，非 A4 打印导向）
- 🖨️ **导出 PDF（打印）** —— 打开浏览器打印对话框（打印内容即渲染后的文档），选择「另存为 PDF」即可生成 PDF

## 特性

- **零依赖、不替换内置功能**：不覆盖 better-sidebar 自带的 Markdown 预览/编辑（预览、编辑、保存、Mermaid 渲染全部保留），只是在工具栏旁**追加**导出按钮
- **所见即所得**：导出的 HTML 内容直接取自内置预览器已渲染的 DOM（含 Mermaid SVG），无需二次渲染
- **保存到 md 同目录**：通过 better-sidebar 的 `/sidebar/api/fs.write` 通道把 HTML 写入 md 所在目录（文件名同 md、扩展名 `.html`）；若会话识别失败自动回退浏览器下载
- **布局跟随原 md 预览**：导出 HTML 使用当前预览主题的配色与排版（深/浅色自动跟随），内容宽度自适应，**不使用 A4 打印尺寸**
- **编辑模式兼容**：若当前处于编辑模式且内容未保存，点击导出会自动切到预览再导出
- **自动跟随**：切换文件、切换预览/编辑模式时，导出按钮自动出现在 Markdown 工具栏上

## 前置

- DSH `dsh web` 可正常运行
- 已安装 [dsh-better-sidebar](https://www.npmjs.com/package/dsh-better-sidebar)（含聚合包 `@linxin666/dsh-web-ui-all` 带入的场景）

## 安装

```sh
dsh plugin --profile web add <dsh-md-export-0.1.0.tgz>
```

装完**重启 dsh web**（新增 bundle 需 host 侧重载），再硬刷新浏览器（Cmd/Ctrl+Shift+R）。

> 侧边栏打开任一 `.md` 文件，工具栏「预览 | 编辑」切换旁即出现「导出 ▼」按钮。

## 使用

1. 在 better-sidebar 打开任意 `.md` 文件（如 `docs/AOI端保存图片逻辑.md`）
2. 点击工具栏「导出 ▼」
3. 选择：
   - **保存 HTML（同目录）**：HTML 直接写入 md 同目录（如 `docs/AOI端保存图片逻辑.html`），页面布局与 md 预览一致
   - **导出 PDF（打印）**：弹出打印对话框，选择「另存为 PDF」保存

## 开发

```sh
node --check lib/client.js   # 语法校验（本插件为手写单文件 client bundle，无构建步骤）
```

- `lib/index.js` —— 宿主侧占位插件（空 apply，使 loader entry 挂载成功）
- `lib/client.js` —— 客户端逻辑：MutationObserver 监听 markdown 工具栏 → 注入导出按钮 + 下拉 → 抓取预览 DOM → `/sidebar/api/fs.write` 保存同目录 / 触发打印

## 实现说明

| 环节 | 方式 |
|---|---|
| 按钮注入 | `MutationObserver` 监听 `document.body`，找到 `.nArs4W_editorModeToggle`（Markdown/HTML 预览器工具栏）且当前文件为 `.md` 时注入 |
| 路径解析 | 从 `.nArs4W_editorPathInput` 的 `title` 属性取 md 绝对路径，输出文件为同目录同名 `.html` |
| 会话识别 | 遍历 localStorage `dsh-sidebar:v1:*` 键，取最新会话 sessionId |
| 保存到同目录 | `POST /sidebar/api/fs.write`（payload: sessionId + 绝对路径 + HTML 内容）；失败回退浏览器下载 |
| HTML 布局 | 从 `.nArs4W_editorMd` 与页面主题读取配色/字体，导出内容宽度自适应（非 A4） |
| PDF 导出 | 相同 HTML 写入隐藏 iframe → `window.print()` → 用户在打印对话框选「另存为 PDF」 |

## 已知限制

- PDF 导出依赖浏览器打印功能（Chrome/Edge 均可「另存为 PDF」），不是直接生成 `.pdf` 二进制；因此 PDF 无法直接保存到 md 同目录
- HTML 保存到同目录依赖会话识别（localStorage）；极端情况下会回退为浏览器下载
- 依赖 better-sidebar 内部 CSS 类名（`nArs4W_` 前缀），若 better-sidebar 大版本升级改类名，需同步更新
- 仅对 `.md` 文件生效；`.markdown` 扩展名同样支持

## License

MIT