black-yt Markdown to DOCX
文件导航
| 序号 | 文件内容概览 | 关键词 | 触发时机 | 文件路径 |
|---|---|---|---|---|
| 1 | 说明 Markdown 转 DOCX 的使用边界和执行入口，覆盖依赖、build_docx.py/count_visible_words.py 参数、本地图片、caption、表格展开、公式降级、字体、输出检查和 /tmp 清理。 |
Markdown to DOCX、Word、.docx、python-docx、build_docx.py、count_visible_words.py、images、caption、HTML img、tables、formula、font、word count、quality check |
触发本 skill 后默认读取；需要把 Markdown 交付为 Word 前；选择脚本参数前；处理图片/表格/公式前；检查 docx 字数、图片、caption 或格式问题前读取 | SKILL.md |
| 2 | 展开从零组织一份 Word 文档的内容工作流，说明 Markdown 材料如何拆成一级章节、图文块、居中图片、caption、目录结构、正文段落和可维护的分文件草稿。 | document workflow、section plan、Heading 1、image-text block、caption、table-to-text、directory structure、split draft、article、report、public draft、PR document | 从零规划 DOCX 文档结构前；把杂乱 Markdown/图片整理成正式 Word 前；需要拆分长文、组织图文块、重写一级章节或统一 caption 时必须读取 | references/docx-workflow-and-structure.md |
使用边界
- 核心技能是把 Markdown 文档转换成可交付的 Word
.docx，不绑定某一种业务场景。 - 适合文章、报告、公告、release note、项目文档、说明书、会议材料、图文解读稿、官网/公众号草稿和对外沟通材料。
- 优先使用本 skill 的
scripts/build_docx.py，不要临时手写一次性转换脚本。 - 图片应是本地相对路径，推荐放在 Markdown 同级的
images/目录。 - 不要依赖远程图片 URL；先下载到项目内再引用。
- 不要把生成文件长期放进
/tmp；临时测试可以放/tmp，测试后必须清理。 - 如果用户要求严格保留复杂 Markdown 表格为 Word 网格表，本脚本不是最佳选择；它更适合把 Markdown 排成可读的 Word 文档和图文块。
- 如果用户要求企业模板、页眉页脚、封面、目录、编号样式、参考文献格式，应在脚本基础上扩展或使用 Word 模板驱动流程。
能力范围
输入能力：
- Markdown 标题、段落、粗体、斜体、inline code、链接。
- 无序列表、有序列表、嵌套列表。
- blockquote。
- fenced code block，按普通文本块进入 Word，不做语法高亮。
- Markdown 图片和 HTML
<img>图片。 - Markdown table，按“图文块”展开为 Word 正文结构。
输出能力：
- 生成独立
.docx文件。 - 嵌入本地图片，而不是保留外链。
- 使用 Word 内置
Title、Heading 1/2/3、Normal、List Bullet、List Number、Quote样式。 - 设置中英文都可读的标题/正文字体。
- 图片居中，caption 居中、小号、斜体。
- 链接按蓝色下划线显示。
- 可用脚本估算 Word 可见字数。
核心流程
- 明确交付目标：
- 普通图文文档：直接使用默认参数。
- 中文正式文档：通常保留
--body-font 等线 --heading-font 黑体。 - 英文文档：可改为
--body-font Calibri --heading-font Arial。 - 图片密集文档：优先在 Markdown 中给
<img>写width。
- 整理 Markdown 和图片：
可以直接生成图片和 caption。<p align="center"><img src="images/a.png" alt="Caption" width="360" /></p>可以控制图片宽度。alt文本会作为图片 caption。- 重复图片默认只保留第一次，避免正文和表格重复插图。
- 转换为 DOCX：
python3 markdown-to-docx/scripts/build_docx.py /path/to/article.md -o /path/to/article.docx
- 如需保留重复图片：
python3 markdown-to-docx/scripts/build_docx.py /path/to/article.md -o /path/to/article.docx --keep-duplicate-images
- 检查可见字数：
python3 markdown-to-docx/scripts/count_visible_words.py /path/to/article.docx
- 人工打开
.docx检查：- 标题层级是否正确。
- 图片是否全部出现。
- caption 是否符合预期。
- 链接是否以蓝色下划线显示。
- 列表、引用、粗体、斜体是否可读。
完整示例：
python3 markdown-to-docx/scripts/build_docx.py ./draft.md \
-o ./draft.docx \
--base-dir . \
--body-font "等线" \
--heading-font "黑体" \
--body-size 11 \
--default-image-width 5.8
python3 markdown-to-docx/scripts/count_visible_words.py ./draft.docx
依赖
安装：
pip install python-docx markdown beautifulsoup4 lxml
检查：
python3 - <<'PY'
import bs4
import docx
import markdown
import lxml
print("ok")
PY
不要在共享环境中擅自安装或升级依赖；需要安装时先征得用户同意。若只是临时测试，优先使用当前项目已有环境或单独临时环境。
输入组织
推荐目录：
document-project/
├── draft.md
├── draft.docx
└── images/
├── overview.png
├── pipeline.png
└── result.png
路径规则：
- 默认情况下，图片相对路径以 Markdown 文件所在目录为基准。
- 如果 Markdown 和图片不在同一项目目录下，用
--base-dir显式指定图片基准目录。 - 路径中尽量不要使用空格、中文标点和过长文件名。
- 不要引用上级目录里的大范围路径，例如
../../...；交付文档应能在单个项目目录中复现。 - 远程图片、base64 图片和本地绝对路径都不推荐作为 Markdown 输入。
Markdown 写法
标题：
# 文档标题
## 脚本参数
`scripts/build_docx.py`：
| 参数 | 必需 | 说明 |
| --- | --- | --- |
| `input` | 是 | Markdown 源文件。 |
| `-o, --output` | 否 | 输出 `.docx` 路径；默认与输入同名。 |
| `--base-dir` | 否 | 解析图片相对路径的目录；默认输入 Markdown 所在目录。 |
| `--keep-duplicate-images` | 否 | 保留重复图片，不跳过后续重复引用。 |
| `--body-font` | 否 | 正文字体，默认 `等线`。 |
| `--heading-font` | 否 | 标题字体，默认 `黑体`。 |
| `--body-size` | 否 | 正文字号，默认 `11`。 |
| `--default-image-width` | 否 | 未显式设置宽度时的图片宽度，单位英寸。 |
`scripts/count_visible_words.py`：
| 参数 | 必需 | 说明 |
| --- | --- | --- |
| `paths` | 是 | 一个或多个 `.docx` 文件。 |
统计说明：
- 英文按 token-like words 统计。
- 中文/中英混排按 CJK 字符数 + 英文 token 数，再乘以经验系数。
- 统计用于估算 Word 可见内容量，不等同于严格出版字数。
## 转换策略
标题策略：
- 文档只应有一个 `#` 主标题。
- 后续章节从 `##` 开始。
- 标题不要只靠加粗段落表达；使用真正 Markdown 标题，Word 里才有清晰层级。
图片策略：
- 每张重要图片都写清楚 `alt`，因为它会变成 caption。
- 宽图使用 `width="520"` 到 `width="580"`。
- 小图、流程图和示意图使用 `width="320"` 到 `width="460"`。
- 如果图片已经含有英文/中文标注，caption 不要重复图片里的完整句子，只写图的名称或作用。
表格策略：
- 如果表格是“解释型内容”，允许展开成图文块。
- 如果表格是“数据型内容”，不要默认用本脚本的展开策略；先确认用户是否接受。
- 数据表若必须保留网格，应该专门修改脚本，不要假装默认转换能保留复杂表格。
字数策略：
- `.docx` 生成后再估算字数，因为图片 caption、表格展开和 HTML 换行会影响可见内容。
- 中文稿用 `calibrated` 看大致篇幅。
- 英文稿用 `word_tokens` 看大致篇幅。
- 字数统计只是排版和投稿前的快速估算，最终以 Word / 目标平台统计为准。
## 质量检查
转换前：
```bash
python3 - <<'PY'
from pathlib import Path
import re
md = Path("/path/to/article.md")
base = md.parent
text = md.read_text(encoding="utf-8")
paths = re.findall(r'!\[[^\]]*\]\(([^)]+)\)|<img[^>]+src=["']([^"']+)["']', text)
missing = []
for a, b in paths:
src = a or b
if src.startswith(("http://", "https://", "data:")):
continue
if not (base / src).exists():
missing.append(src)
print("missing:", missing)
raise SystemExit(1 if missing else 0)
PY
转换后：
python3 markdown-to-docx/scripts/count_visible_words.py /path/to/article.docx
必须人工查看：
- Word 是否能正常打开。
- 图片是否被嵌入，不是外链。
- caption 是否重复或缺失。
- 表格展开是否符合文档阅读顺序。
- 中英文混排字体是否可读。
- 标题是否过密，是否需要拆段。
- 代码块是否因为长行影响可读性。
- 生成文件是否放在用户指定目录，而不是遗留在临时目录。
常见问题
- 图片缺失：确认
--base-dir和 Markdown 图片路径是否一致。 - 图片重复：默认会跳过重复
src；需要全部保留时加--keep-duplicate-images。 - 表格不像 Word 表格：这是预期行为，本脚本按图文块展开表格。
- 远程图片没有出现：先下载图片到本地项目目录，再使用相对路径。
- 字体不符合要求：用
--body-font和--heading-font显式指定。 - 需要严格模板/页眉/页脚/参考文献样式：应在脚本基础上扩展，或改用 Word 模板驱动流程。
- Word 里图片太大：在 Markdown HTML 图片里写
width，或调低--default-image-width。 - Word 里内容太挤：可以增大
paragraph_format.space_after，或拆分 Markdown 长段落。 - Word 里代码块不好看：这不是代码文档专用渲染器；需要代码高亮时应扩展脚本或使用 Pandoc/template 流程。