# Markdown Formatter

> 当用户要求格式化 markdown 文档、修复语法错误、优化排版、智能分段、清理冗余内容、检查文档质量时使用

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

---


# Markdown 文档格式化 Skill

## 工作流程

当用户要求格式化文档时，按以下顺序执行：

### 1. 语法检查和修复

使用 markdown-checker 脚本检查文档：

```bash
python3 ~/.claude/skills/markdown-checker/scripts/check_markdown.py "文件路径"
```

**修复优先级：**
- ❌ 错误：必须修复（链接格式、代码块闭合、列表格式）
- ⚠️ 警告：建议修复（行尾空格、标点符号、缩进）
- ℹ️ 提示：可选修复（排版建议）

**注意：**
- YAML frontmatter 的 `---` 会被误报为列表，忽略这个错误
- 只修复真正影响语法的问题，不要过度优化

### 2. 智能分段

**分段原则：**
- 长段落（超过 100 字符）需要分段
- 在句号、问号、感叹号后分段
- 在冒号、分号后分段（如果后面是完整句子）
- 保持语义完整性，不要破坏逻辑连贯性

**分段示例：**
```
原句：今天研究了语音输入法，基于 fun-asr-nano，很有意思。其实核心是速度和准确度。

分段后：
今天研究了语音输入法，基于 fun-asr-nano，很有意思。

其实核心是速度和准确度。
```

### 3. 排版优化

**必须修复：**
- 移除行尾多余空格
- 移除连续空行（最多保留 2 行）
- 修复明显的排版错误

**可选优化：**
- 中英文之间添加空格（如 `。Claude` → `。 Claude`）
- 中文标点后添加空格（如果后面是英文）

**为什么：**
- 必须修复的问题影响文档质量
- 可选优化是个人偏好，不要过度修改

### 4. 内容清理

**检查项：**
- 移除重复的空行
- 统一列表符号（使用 `-` 或 `*`，保持一致）
- 检查 YAML frontmatter 格式
- 验证图片链接是否有效

### 5. Emoji 图片引用处理

**识别模式：**
```
![😂](https://abs-0.twimg.com/emoji/v2/svg/1f602.svg "乐极而泣脸")
```

**处理规则：**
- 如果 alt text 中包含 emoji（如 `😂`），直接用 emoji 替代整个图片引用
- 如果 alt text 中没有 emoji，删除整个图片引用
- Twitter/X 的 emoji 图片链接通常来自 `abs-0.twimg.com/emoji/v2/svg/`

**处理示例：**
```
原内容：![😂](https://abs-0.twimg.com/emoji/v2/svg/1f602.svg "乐极而泣脸")
替换后：😂

原内容：![图像](https://abs-0.twimg.com/emoji/v2/svg/1f602.svg)
替换后：（删除）
```

**为什么：**
- Emoji 图片在阅读时会占满一个很大的区域，影响阅读体验
- 直接使用 emoji 更简洁，不占用额外空间
- Twitter/X 的 emoji 链接是 SVG 格式，不适合在 markdown 中直接显示

## 用户偏好

**格式化风格：**
- 优先保证语法正确性
- 保持原文语义不变
- 段落落落要合理，便于阅读
- 不要过度修改原文

**处理 clipping 文档时：**
- 这些文档通常从 Twitter/X 等平台抓取
- 内容可能很密集，需要合理分段
- 保留原始信息，只优化格式

## 验证步骤

格式化完成后：
1. 重新运行 markdown-checker 确认错误已修复
2. 读取文件确认内容语义正确
3. 告诉用户修复了哪些问题
4. 询问是否需要进一步优化

## 特殊情况

**不要自动修改：**
- 代码块内容（除非用户明确要求）
- 特殊格式（如表格、数学公式）
- 用户自定义的格式

**需要确认：**
- 大量修改（超过 10 处）先告知用户
- 涉及内容重写的操作先询问
- 不确定是否应该修改的地方先询问