# markdown-util

**Repository Path**: xinhun1994/markdown-util

## Basic Information

- **Project Name**: markdown-util
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-28
- **Last Updated**: 2026-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<!-- @AI-Begin Wp3n7 20260728 Claude -->
# markdown-util

> Office 文档与 Markdown 之间的双向转换桌面工具，支持 Windows / macOS / Linux。本地运行，文件不上传。

<!-- @AI-Begin Rk7mP 20260729 Claude -->
基于 Tauri 2 的跨平台桌面应用，把 Word / Excel / PowerPoint 与 Markdown 互转。Word 走 Pandoc（保真最佳），Excel 走 Rust 原生 crate（calamine 读 + rust_xlsxwriter 写），<!-- @AI-Begin P9q0R 20260730 Claude -->PPT 走 ppt-rs cli feature（pptx↔md 双向），<!-- @AI-End P9q0R 20260730 Claude -->PDF 走 pdf-extract + genpdfi（双向）。所有转换在本机完成。
<!-- @AI-End Rk7mP 20260729 Claude -->

## 功能

| 格式 | 方向 | 状态 | 引擎 |
|------|------|------|------|
| Word (.docx) ↔ Markdown | 双向 | ✅ 已实现 | Pandoc（Tauri sidecar 子进程） |
<!-- @AI-Begin Lw3nQ 20260729 Claude -->
| Excel (.xlsx) ↔ Markdown | 双向 | ✅ 已实现 | Rust crate（calamine 读 + rust_xlsxwriter 写） |
<!-- @AI-End Lw3nQ 20260729 Claude -->
<!-- @AI-Begin P7tQx 20260730 Claude -->
| PowerPoint (.pptx) ↔ Markdown | 双向 | ✅ 已实现 | ppt-rs cli feature（pptx↔md 双向） |
| PDF (.pdf) ↔ Markdown | 双向 | ✅ 已实现 | pdf-extract 读 + genpdfi 写（pulldown-cmark 解析） |
<!-- @AI-End P7tQx 20260730 Claude -->

> 保真度说明：Word↔Markdown 效果最好；<!-- @AI-Begin F6gHa 20260730 Claude -->Excel/PPT/PDF 因格式特性（公式、多 sheet、版式、定位、版面）转换有损<!-- @AI-End F6gHa 20260730 Claude -->，仅做结构化文本提取/生成。

## 技术栈

- **Tauri 2**：Rust 核心 + 系统 WebView，安装包小、原生跨平台
- **Vue 3 + TypeScript + Vite**：前端
- **Pandoc**：Word 转换引擎，以 Tauri sidecar 方式打包调用（不走系统 PATH）
<!-- @AI-Begin Vt8xR 20260729 Claude -->
- **calamine / rust_xlsxwriter**：Excel 读写（Rust 原生 crate，编译进二进制，无需外部下载）
<!-- @AI-Begin R5vTb 20260730 Claude -->- ppt-rs（cli feature）：PowerPoint ↔ Markdown 双向读写；zip：PPTX 图片提取；pdf-extract / genpdfi / pulldown-cmark：PDF 读写<!-- @AI-End R5vTb 20260730 Claude -->
<!-- @AI-End Vt8xR 20260729 Claude -->

## 环境要求

- [Node.js](https://nodejs.org) 18+（推荐 20+）
- [Rust](https://www.rust-lang.org/) stable —— Windows 需 MSVC C++ 工具链（随 Visual Studio Build Tools 安装）
- 平台 WebView：Windows 自带 WebView2，macOS 自带 WebKit，Linux 需 `webkit2gtk`
- [Pandoc](https://pandoc.org/)：仅用于获取 sidecar 二进制（见下）

## 快速开始（开发模式）

```bash
cd doc-converter
npm install
npm run tauri dev        # 首次 Rust 编译约 5-15 分钟
```

> Windows 上用 Git Bash 时若提示找不到 cargo，先执行 `export PATH="$HOME/.cargo/bin:$PATH"`。

应用窗口打开后：选择文件 → 选择转换方向（docx→md 或 md→docx）→ 选择输出路径 → 转换。

### Pandoc sidecar 二进制

<!-- @AI-Begin gH2wN 20260729 Claude -->
仓库**不包含** Pandoc 二进制（约 231MB，已 gitignore）。首次执行 `npm run tauri build` 或 `npm run tauri dev` 时会自动触发 `pretauri` 钩子，通过 `doc-converter/scripts/fetch-pandoc.mjs` 从 GitHub Releases 拉取 **Pandoc 3.10**（当前锁定版本），完成 SHA256 校验、解压、按 target triple 重命名后放到 `doc-converter/src-tauri/` 目录。

- 幂等：若目标二进制已存在则跳过下载
- 支持平台：`x86_64-pc-windows-msvc`、`x86_64-unknown-linux-gnu`、`aarch64-unknown-linux-gnu`、`aarch64-apple-darwin`、`x86_64-apple-darwin`
- 手动触发下载：`cd doc-converter && npm run fetch-pandoc`
- 网络不通时脚本会打印手动下载指引，也可直接从 [Pandoc 3.10 releases](https://github.com/jgm/pandoc/releases/tag/3.10) 下载并按 `pandoc-<triple>[.exe]` 命名放入 `src-tauri/`
<!-- @AI-End gH2wN 20260729 Claude -->

## 构建

```bash
cd doc-converter
npm install
npm run tauri build      # 产物在 src-tauri/target/release/bundle/
```

<!-- @AI-Begin iJ4kL 20260729 Claude -->
首次构建会自动下载 Pandoc 3.10 sidecar（见下节）。三平台产物由 `.github/workflows/build.yml` 在 GitHub Actions 上构建：Windows NSIS/MSI、macOS DMG（arm64 + x64）、Linux DEB/AppImage/RPM。手动触发：Actions → build-doc-converter → Run workflow。
<!-- @AI-End iJ4kL 20260729 Claude -->

## 项目结构

```
doc-converter/
├── src/                      # Vue 前端
│   └── App.vue               # 极简 UI（文件选择 / 方向 / 输出 / 转换 / 日志）
├── src-tauri/
│   ├── src/lib.rs            # 核心转换逻辑 + selftest
│   ├── tauri.conf.json       # sidecar 配置（bundle.externalBin）
│   ├── capabilities/         # shell sidecar 权限
│   └── pandoc-<triple>.exe   # sidecar 二进制（不入库，需自备）
└── m1-test/                  # 测试夹具（test.md、sample.png）
```

## 路线图

- ✅ **M1**：Word ↔ Markdown（Pandoc sidecar）
<!-- @AI-Begin Km4pS 20260729 Claude -->
- ✅ **M2**：Excel ↔ Markdown（Rust crate：calamine 读 + rust_xlsxwriter 写）
<!-- @AI-End Km4pS 20260729 Claude -->
<!-- @AI-Begin M3aR9 20260730 Claude -->
- ✅ **M3**：PowerPoint ↔ Markdown（ppt-rs cli feature + ZIP 图片提取）
<!-- @AI-End M3aR9 20260730 Claude -->
<!-- @AI-Begin H8kLm 20260730 Claude -->
- ✅ **M3.5**：PDF ↔ Markdown（pdf-extract 读 + genpdfi 写）
<!-- @AI-End H8kLm 20260730 Claude -->
<!-- @AI-Begin kM7nO 20260729 Claude -->
- ✅ **M4**：三平台打包（Windows/macOS/Linux）+ Pandoc 3.10 构建期自动下载（签名待后续）
<!-- @AI-End kM7nO 20260729 Claude -->
<!-- @AI-Begin K2nWp 20260730 Claude -->- ⬜ **M5**：预览 / 批量 / 选项面板 + 图片输出优化<!-- @AI-End K2nWp 20260730 Claude -->

## 已知局限

<!-- @AI-Begin F6g7H 20260730 Claude -->- docx→md 图片通过 --extract-media 提取到 media/ 子目录并后处理为 GFM 相对路径语法；关闭"提取图片"开关时图片不提取<!-- @AI-End F6g7H 20260730 Claude -->
<!-- @AI-Begin Nq9wT 20260729 Claude -->
- Excel 转换有损：公式只存计算值，格式/图表/合并单元格丢失；MD->Excel 单元格一律按字符串写入（保前导零/长 ID，不推断数字类型）；<!-- @AI-Begin Dt5rW 20260729 Claude -->日期输出可读格式（已开 calamine `dates` feature，按日期/时间/日期时间自动格式化；转换失败回退序列号）<!-- @AI-End Dt5rW 20260729 Claude -->
<!-- @AI-Begin L9qXd 20260730 Claude -->- PPT 转换有损：动画/过渡/视频/音频/精确布局丢弃，仅 pptx->md 单向；PDF->MD 只提取文本（图片/表格/格式丢失），MD->PDF 需系统 TrueType 字体<!-- @AI-End L9qXd 20260730 Claude -->
<!-- @AI-End Nq9wT 20260729 Claude -->
- Pandoc 错误信息在中文 Windows 下可能乱码（stderr 编码问题）
<!-- @AI-Begin mP1qR 20260729 Claude -->
- 打包产物暂未签名：Windows NSIS/MSI 首次运行会触发 SmartScreen 警告，macOS DMG 需右键"打开"绕过 Gatekeeper（M4 后续版本考虑接入签名证书）
<!-- @AI-End mP1qR 20260729 Claude -->

## 自测

内置 selftest 走真实 sidecar 链路验证往返保真与错误路径（需先构建出可执行文件）：

```bash
cd doc-converter
DOC_CONV_SELFTEST=results.txt DOC_CONV_TESTMD=m1-test/test.md ./target/debug/doc-converter.exe
```

<!-- @AI-Begin Pr5xU 20260729 Claude -->
Excel（M2）转换不依赖 sidecar，在 `doc-converter/src-tauri` 下用 `cargo test` 跑 Rust 单元测试，覆盖往返保真与边界用例（前导零/长 ID 保真、数据行不被误吞、多表格继承名等）。
<!-- @AI-End Pr5xU 20260729 Claude -->

## License

本应用代码采用 **Apache-2.0**。注意：分发的应用会捆绑 [Pandoc](https://pandoc.org/) 二进制（GPLv2），以独立子进程方式调用，不与本项目代码静态/动态链接；Pandoc 二进制本身的许可与著作权归其作者。

---

## English Overview

**markdown-util** is a cross-platform desktop app (Tauri 2) that converts between Office documents (Word / Excel / PowerPoint) and Markdown — locally, offline, no file uploads. Word conversion uses Pandoc (bundled as a Tauri sidecar) for best fidelity; <!-- @AI-Begin Qs6yV 20260729 Claude -->Excel uses Rust-native crates (calamine / rust_xlsxwriter) and is lossy; <!-- @AI-Begin E4fYc 20260730 Claude -->PowerPoint uses ppt-rs (pptx->md only, md->pptx pending) and is lossy; PDF uses pdf-extract + genpdfi and is lossy.<!-- @AI-End E4fYc 20260730 Claude --><!-- @AI-End Qs6yV 20260729 Claude --> See the Chinese section above for current status, prerequisites, build steps, and roadmap.
<!-- @AI-End Wp3n7 20260728 Claude -->