# Quarto

> Quarto 文档转换技能。当需要将 docx 转换为可编译的 Quarto 项目时触发。

- Skill: `zengtianli/quarto` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zengtianli/quarto`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zengtianli/quarto/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: zengtianli (https://skillmd.com/u/zengtianli)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zengtianli/quarto

---


# Quarto 文档转换技能

## 核心价值

1. **源码化**：docx 变成"可编译"形式，纯文本进 git
2. **数据驱动**：改 data.yml，重新渲染，不再手动改 docx
3. **版本控制**：纯文本 diff，告别 "方案_v1_final_最终版.docx"
4. **可复用**：同类项目复制模板，换数据即可

---

## 一键转换命令

```bash
# [已废弃] docx_to_quarto.py <xxx.docx>
```

### 输入输出

```
输入：xxx.docx

输出：
quarto_xxx/
├── data.yml           # 数据配置
├── data_mapping.json  # 数据映射
├── build.py           # 构建脚本
├── _quarto.yml        # Quarto 配置
├── render.sh          # 渲染脚本
├── .gitignore
└── src/
    └── xxx.qmd        # 源文件（保持原名）
```

---

## 适用场景判断

| 类型 | 是否适合 | 原因 |
|------|----------|------|
| **我方成果报告** | ✅ 核心目标 | 需要版本控制和迭代 |
| **多县市同类报告** | ✅ 非常值得 | 一个模板，N 县复用 |
| **学术论文** | ✅ 适合 | 数据驱动，便于修改 |
| 招标/投标文件 | ❌ | 外部来源 |
| 参考案例 | ❌ | 外部来源 |
| 临时草稿 | ❌ | 用完就扔 |

---

## 推荐策略

### 优先 Quarto 化

1. **生态流量县市报告**：一个模板，10+ 县市复用
2. **有迭代需求的报告**：需要多次修改数据的文档

### 暂不 Quarto 化

- 参考资料（外部来源）
- 招投标文件
- 已完成的旧项目

---

## 工作量估算

每个 docx Quarto 化：3-5 小时

1. 分析文档，识别数据点（0.5-1h）
2. 提取数据到 data.yml（0.5h）
3. 转换内容为 qmd 模板（1-2h）
4. 编写 build.py 数据校验（0.5h）
5. 测试渲染（0.5h）

---

## 目录结构示例

```
生态流量/
├── _templates/                    # 共享模板
│   ├── 水库核定报告.qmd
│   └── build.py
├── 县市项目/
│   ├── 丽水_景宁/
│   │   ├── data.yml              # 景宁的数据
│   │   ├── _variables.yml        # 自动生成
│   │   └── render.sh
│   ├── 丽水_缙云/
│   │   ├── data.yml              # 缙云的数据
│   │   └── ...
```

---

## 复杂格式处理

- **表格**：Markdown 表格或 CSV + 模板
- **图片**：放在项目目录，qmd 中引用
- **复杂格式**：用 docx 模板 (`--reference-doc`)

---

## 实际案例

```bash
# 转换景宁生态流量报告
# [已废弃] docx_to_quarto.py \
    "projects/生态流量/县市项目/丽水_景宁/成果/0景宁县小型水库工程生态流量核定与保障实施方案0123.docx"
```

生成：
```
projects/生态流量/县市项目/丽水_景宁/成果/
└── quarto_0景宁县小型水库工程生态流量核定与保障实施方案0123/
    ├── src/0景宁县小型水库工程生态流量核定与保障实施方案0123.qmd
    ├── data.yml
    └── ...
```