# Markdown Formatter

> Format and optimize Markdown content, with special support for post-translation processing. Use when fixing Markdown syntax, adjusting layout, ensuring formatting consistency, or optimizing translated documents.

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

---


# Markdown Formatter

专门处理 Markdown 文档的格式化、布局优化和语法修正，特别支持翻译后文档的优化处理。

## 核心功能

### 1. 语法验证与修正

- 检查并修正 Markdown 语法错误
- 统一标题层级（避免跳级）
- 修正列表格式（有序/无序）
- 确保代码块语言标识正确

### 2. 图片处理

- 验证图片引用路径的正确性
- 使用 zai-mcp-server 分析图片内容
- 生成合适的图片 alt 文本
- 统一图片命名规范

### 3. 表格格式化

- 确保表格对齐正确
- 修正表格分隔符
- 处理表格内容溢出
- 添加表格标题和说明

### 4. 公式处理

- 验证 LaTeX 公式语法
- 确保行内/块级公式正确显示
- 添加公式说明文字
- 处理复杂公式的换行

## Workflow

### 输入处理

1. 接收原始 Markdown 内容
2. 分析文档结构和格式问题
3. 识别需要修正的内容类型

### 格式化步骤

1. **标题结构**

   - 检查标题层级连续性
   - 统一标题风格（是否加粗等）
   - 生成目录结构（如需要）

2. **段落格式**

   - 统一段落间距
   - 修正换行符使用
   - 处理多余空行

3. **列表格式**

   - 统一列表符号
   - 修正嵌套列表缩进
   - 处理列表项的延续

4. **链接处理**

   - 验证链接有效性
   - 统一链接格式
   - 处理相对路径

5. **图片优化**
   - 检查图片路径
   - 分析图片内容生成描述
   - 优化图片大小引用

### 输出生成

1. 返回格式化后的 Markdown
2. 提供修改日志
3. 标记未解决的问题

## 使用场景

### 文档后处理

```
格式化这个 Markdown 文档，修正所有语法错误：document.md
```

### 图片优化

```
检查文档中的所有图片，确保路径正确并添加描述：article.md
```

### 表格修复

```
修复这个文档中的表格格式问题：report.md
```

### 综合格式化

```
全面格式化这个 Markdown 文档，确保所有元素都正确显示：guide.md
```

### 翻译后优化

```
优化这个翻译后的文档，修复格式和中英文混排问题：translated_doc.md
```

### 术语一致性检查

```
检查文档中的术语翻译是否一致：technical_doc.md
```

## 检查清单

### 结构检查

- [ ] 标题层级是否连续
- [ ] 章节划分是否合理
- [ ] 目录是否完整（如有）

### 格式检查

- [ ] Markdown 语法是否正确
- [ ] 列表格式是否统一
- [ ] 代码块是否正确标记

### 媒体检查

- [ ] 图片路径是否有效
- [ ] 图片描述是否准确
- [ ] 公式显示是否正确

### 链接检查

- [ ] 内部链接是否有效
- [ ] 外部链接格式是否规范
- [ ] 锚点是否正确

## 特殊处理

### 技术文档

- 保留代码示例的原始格式
- 确保技术术语的一致性
- 维护 API 文档的特殊格式

### 学术文档

- 保持引用格式的一致性
- 确保公式的学术规范
- 处理脚注和参考文献

### 多语言文档

- 标记不同语言部分
- 统一混合语言的格式
- 处理特殊字符和编码

### 翻译后文档处理

- **中英文混排优化**：调整中英文之间的空格
- **术语一致性验证**：检查专业术语翻译的一致性
- **格式适配**：确保中文排版符合规范
- **链接本地化**：检查并修复翻译后的链接引用
- **图片描述本地化**：将图片 alt 文本翻译为中文
- **表格内容调整**：优化中文在表格中的显示

### 批次文档合并

- 处理批次间的衔接
- 统一格式风格
- 合并重复的标题
- 维护文档连续性

## 输出格式

返回结构化结果：

```json
{
  "formatted_content": "格式化后的 Markdown 内容",
  "changes": [
    {
      "type": "标题修正",
      "description": "修正了第 3 级标题的层级"
    }
  ],
  "issues": [
    {
      "type": "图片路径",
      "description": "图片 images/fig1.png 不存在",
      "suggestion": "请检查图片路径或更新引用"
    }
  ],
  "statistics": {
    "total_changes": 15,
    "critical_issues": 2,
    "warnings": 3
  }
}
```