Markdown Master

Markdown Master

使用前准备

首先检查并安装依赖：

# 检查 Python 是否可用
python --version

# 安装可选依赖（convert.py 需要）
pip install python-docx markdown beautifulsoup4 weasyprint pyyaml

注意：structure.py / quality.py / files.py 仅使用 Python 标准库，无需额外安装即可使用。只有 convert.py 需要上述依赖。

核心工作流程

场景 1：准备正式发布的中文文档

当用户需要把一份 Markdown 文档整理成正式版本时：

1. 先做格式检查：python ${SKILL_DIR}/scripts/quality.py doc.md lint --fix
2. 再做中文排版优化：python ${SKILL_DIR}/scripts/quality.py doc.md zhlint --fix
3. 添加章节编号：python ${SKILL_DIR}/scripts/structure.py doc.md numbering add --h1 "第{1}章 " --h2 "{1}.{2} " --h3 "（{3}）"
4. 生成目录：python ${SKILL_DIR}/scripts/structure.py doc.md toc generate
5. 检查链接：python ${SKILL_DIR}/scripts/quality.py doc.md linkcheck
6. 导出为 Word/PDF：python ${SKILL_DIR}/scripts/convert.py doc.md --to docx

场景 2：合并多篇文档

当用户有多份 Markdown 文件需要合并成一份时：

1. 合并文件：python ${SKILL_DIR}/scripts/files.py merge file1.md file2.md -o combined.md
2. 统一调整标题层级（如果需要）：python ${SKILL_DIR}/scripts/structure.py combined.md heading upgrade --levels 1
3. 后续同场景 1（lint → zhlint → 编号 → 目录 → 导出）

场景 3：拆分长文档

当用户有一份很长的文档需要按章节拆分成多个文件时：

1. 拆分：python ${SKILL_DIR}/scripts/files.py split doc.md --by h2
2. 检查拆分结果

命令速查

structure.py — 结构操作

所有操作默认覆盖原文件，使用 -o output.md 输出到新文件。

编号模板语法

N 范围是 1-6，对应标题级别 H1-H6。空模板字符串表示该级标题不添加编号。

YAML 配置文件格式

h1: "第{1}章 "
h2: "{1}.{2} "
h3: "（{3}）"
h4: ""
h5: ""
h6: ""
start_from: 1

常见编号用法示例

# 技术文档风格（1/1.1/1.1.1）
python ${SKILL_DIR}/scripts/structure.py doc.md numbering add --h1 "{1} " --h2 "{1}.{2} " --h3 "{1}.{2}.{3} "

# 中文章节风格（第1章/1.1/（1））
python ${SKILL_DIR}/scripts/structure.py doc.md numbering add --h1 "第{1}章 " --h2 "{1}.{2} " --h3 "（{3}）"

# 学术风格（I/A/1/a）
python ${SKILL_DIR}/scripts/structure.py doc.md numbering add --h1 "{1:R} " --h2 "{2:A} " --h3 "{3} " --h4 "{4:a} "

# 保存当前配置为模板
python ${SKILL_DIR}/scripts/structure.py doc.md numbering add --h1 "第{1}章 " --h2 "{1}.{2} " --save-config chinese_chapter.yaml

# 使用保存的配置
python ${SKILL_DIR}/scripts/structure.py doc.md numbering add --config chinese_chapter.yaml

quality.py — 质检操作

输出格式：[L行号] 问题描述，最后汇总问题数。无问题输出 ✓ No issues found。

lint 检查项：

• ✗ 标题层级跳跃（H1 -> H3）
• ✗ 文件缺少 H1
• ✓ 连续 3 行以上空行
• ✗ 代码块未指定语言

zhlint 检查项：

• ✓ 中文与英文/数字间缺空格
• ✓ 中文语境中使用半角标点

convert.py — 格式转换

python ${SKILL_DIR}/scripts/convert.py <input.md 或 目录/ --to <format> [-o output] [--template template.docx]

输入为目录时批量转换所有 .md 文件。

转换为 DOCX 时必须使用 Word 模板：未传 --template 时，convert.py 自动使用技能内置的 ${SKILL_DIR}/assets/word-template.docx；只有用户明确指定其他模板时，才通过 --template 覆盖该默认值。

DOCX 中仅普通正文段落首行缩进 2 字符；标题、列表、引用、代码块、图片题注和表格内容不设置首行缩进。

Markdown 图片的 alt 文本作为图片题注，并应用 Word 模板中的 Caption 段落样式；题注字体、字号、颜色、对齐和间距均由模板控制。

无序列表按列表块自动排版：2-4 项、每项不超过 40 字且无嵌套或复杂内容时，应用 Word 模板的 List Bullet（"列表项目符号"）样式；其余无序列表转换为无项目符号的正文条目。短列表的圆点、缩进和间距完全由模板控制。

files.py — 文件级操作

# 拆分
python ${SKILL_DIR}/scripts/files.py split <input.md> --by h1|h2|h3 [--output-dir DIR]

# 合并（支持文件列表或目录）
python ${SKILL_DIR}/scripts/files.py merge <file1> [file2 ...] -o output.md [--separator SEP]

split 默认输出到 <input_dir>/split_output/，文件名为 XX_<标题文本>.md。 merge 输入目录时，按文件名字母序合并所有 .md 文件。