markdown-split
Intelligently split a large Markdown document into multiple files based on heading level. Automatically detects the optimal split level or allows manual specification. Use this skill when you need to
SKILL.md.codebuddy/skills/markdown-split/SKILL.md
GitHubMarkdown Split Skill
智能拆分大型 Markdown 文档。自动分析文档结构,选择最佳拆分级别。
使用方法
python3 .codebuddy/skills/markdown-split/scripts/split_markdown.py <input_file> [options]
参数说明
| 参数 | 必填 | 说明 |
|---|---|---|
input_file |
是 | 输入的 Markdown 文件路径 |
--output-dir, -o |
否 | 输出目录,默认为输入文件所在目录下的 split_output/ |
--level, -l |
否 | 拆分的标题级别 (1-6),不指定则自动检测 |
--prefix, -p |
否 | 输出文件名前缀,默认为空 |
--no-index |
否 | 不生成索引文件 |
示例
# 自动检测拆分级别(推荐)
python3 scripts/split_markdown.py docs/features.md --output-dir docs/design
# 手动指定按二级标题拆分
python3 scripts/split_markdown.py docs/features.md --level 2 -o docs/design
# 按三级标题拆分
python3 scripts/split_markdown.py docs/guide.md -l 3
# 添加文件名前缀
python3 scripts/split_markdown.py docs/guide.md -o ./chapters -p "chapter_"
智能检测逻辑
脚本会自动分析文档的标题结构,按以下策略选择拆分级别:
- 统计各级标题数量 (H1-H6)
- 选择数量在 2-15 之间的最高级别标题
- 如果最高级别只有 1 个,自动选择下一级别
例如,对于以下文档:
# 游戏设计文档 ← H1: 1 个(作为文档标题,不适合拆分)
### 1. 游戏概述 ← H3: 5 个(自动选择此级别拆分)
### 2. 核心机制
### 3. 游戏对象
...
输出:
文档标题结构分析:
H1 (#): 1 个
H3 (###): 5 个
自动检测拆分级别: H3 (###)
找到 5 个章节
输出说明
假设输入文件包含以下结构(H3 作为主要章节):
# 游戏设计文档
### 1. 游戏概述
内容...
### 2. 核心机制
内容...
### 3. 游戏对象
内容...
将生成以下文件:
docs/design/
├── index.md # 索引文件
├── 00_前言.md # H3 标题前的内容
├── 01_1_游戏概述.md
├── 02_2_核心机制.md
└── 03_3_游戏对象.md
特性
- 智能检测:自动分析文档结构,选择最佳拆分级别
- 手动覆盖:支持
--level参数手动指定拆分级别 - 代码块保护:正确处理代码块中的
#符号 - 自动序号:文件名自动添加序号
- 索引生成:自动生成目录索引文件