# Obsidian Markdown Formatter

> Optimize Obsidian Markdown note formatting and typography. Use this skill when the user asks to format, optimize, clean up, or beautify any .md note in their Obsidian vault. Trigger phrases include: "格式化", "排版优化", "整理笔记", "美化格式", "优化格式", "format this note", "clean up markdown", "fix formatting". Also use when the user provides a markdown file with obvious formatting issues like missing code language tags, garbled OCR text, inconsistent heading levels, plain text that should be lists, misaligned tables, or poor spacing.

- Skill: `yuanji888/obsidian-markdown-formatter` (Agent Skill, multi-file: 18 files)
- Install (CLI): `npx skillmds@latest add yuanji888/obsidian-markdown-formatter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yuanji888/obsidian-markdown-formatter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: yuanji888 (https://skillmd.com/u/yuanji888)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/yuanji888/obsidian-markdown-formatter

---


# Obsidian Markdown 笔记格式优化

优化 Obsidian 知识库中 Markdown 笔记的排版格式，让笔记整洁、易读、结构清晰。

## 核心原则

- **只改格式，不改内容**：不改变笔记的实际知识内容，只优化呈现方式
- **保留 Obsidian 特性**：保持 Wiki 链接、YAML frontmatter、图片嵌入等不变
- **保持用户风格**：尊重用户原有的写作风格和用词习惯
- **先读后改**：每项优化前先完整读取文件，确认当前状态

## 格式化步骤

按以下顺序逐项检查并优化：

### 1. 代码块规范化

自动识别无语言标签的代码块并添加语言标记；统一非缩进敏感语言为 4 空格缩进，纠正 Python/YAML 的混用缩进。

**语言标记映射：**

| 代码类型 | 标记 |
|----------|------|
| C# | `csharp` |
| Python | `python` |
| JavaScript / TypeScript | `js` / `ts` |
| SQL | `sql` |
| JSON | `json` |
| 命令行 | `bash` 或 `shell` |
| 不确定 | `text` 或不加 |

**示例：**
```
修复前：
```
Form Form=new Form();
From.SnowDialog();
```

修复后：
```csharp
Form form = new Form();
form.ShowDialog();
```
```

### 2. 乱码与标点修复

> **⚠️ 核心原则**：代码块中的标识符（变量名、类名、方法名、类型名）**一律使用标准英文**。
> 中文只能出现在：注释、字符串字面量、正文说明文字。
> 不要将中文变量名视为"教学用途"而保留——它们几乎总是 OCR/翻译错误。

**检查项：**
- 中文翻译混入代码（`字节b = 10` → `byte b = 10`）
- OCR 识别错误（`长长值` → `longValue`，`nemaspace` → `namespace`）
- 全角标点混入代码（`；` → `;`，`。` → `.`，`，` → `,`）
- 中文类名/变量名在代码块中（`public class 大学生` → `public class CollegeStudent`）

**常见映射：**

| 中文 | 英文 |
|------|------|
| `字节` | `byte` |
| `整数` | `int` |
| `字符串` | `string` |
| `双精度` / `双双值` | `double` / `doubleValue` |
| `浮点` / `浮动浮动值` | `float` / `floatValue` |
| `布尔` | `bool` |
| `长长值` | `longValue` |
| `水果` | `fruits` |
| `大学生` | `CollegeStudent` |
| `专业` | `Major` |
| `连接状态` | `isConnected` |

### 3. 标题层级补全

**检查项：**
- 是否跳级使用（H1 下直接到 H3，缺少 H2）
- 同级子标题级别是否统一
- 是否有重复的标题名

**处理方法：**
- 确保标题不跳级：`#` → `##` → `###` → `####`
- 同级子标题保持同一级别
- 合并或区分重复标题（如多处 `### 实例` 合并或改为具体名称）

### 4. 纯文本转列表

**检查项：**
- 列举型内容是否用纯文本分行而非 Markdown 列表
- 有前后逻辑或步骤的内容是否散落

**处理方法：**
- 并列项 → `-` 无序列表
- 有顺序关系的步骤 → `1.` 有序列表
- 术语+解释的格式 → 表格或定义列表

### 5. 表格美化与对齐

**检查项：**
- 表格是否缺少对齐分隔行 `|---|`
- 分隔行与标题列数是否一致
- 列内代码元素是否需要用反引号包裹

**处理方法：**
- 补全缺漏的表格边框与对齐分隔行
- 表格内的关键字、类型名、变量用 `` ` `` 包裹
- 保持列宽美观

### 6. 中英文盘古间距

> **⚠️ 最常遗漏的优化项**，务必全文逐句检查，强制添加。

**检查项：**
- 中文与英文之间是否缺少空格
- 中文与数字之间是否缺少空格
- 中文与行内代码 `` `xxx` `` 之间是否缺少空格
- 标题中的中英文混合（`## SQL基础`）

**处理方法：**
- 中文字符后紧跟英文/数字 → 加空格
- 英文/数字后紧跟中文字符 → 加空格
- 中文与行内代码之间 → 加空格
- 中文标点（。，；：）与英文之间 → 不空格

**示例：**
```
修复前：C#中的类型转换
修复后：C# 中的类型转换

修复前：## SQL基础
修复后：## SQL 基础
```

### 7. 冗余空行压缩

**检查项：**
- 连续 3 个及以上的空行
- 重复的标题或段落
- 多余的 `---` 分隔线

**处理方法：**
- 连续空行（3+）压缩为最多 1 个空行
- 合并重复标题下的内容
- 保留有意义的章节分隔线，删除多余的

### 8. 章节智能分隔

**检查项：**
- 大章节（H1）之间是否需要视觉分隔

**处理方法：**
- 正文中间的 H1 大章之间添加 `---` 分隔线
- **文章开头的第一个 H1 之前不添加**
- 分隔线前后各留一个空行
- 不要在 H2 小节之间随意加分隔线
- 规则：全文 N 个 H1 → N-1 条分隔线

### 9. 排版垂直留白

- 段落之间保持一个空行
- 标题、代码块、表格、独立列表块前后各一个空行
- 列表内部嵌套保持紧凑（不加多余空行）

### 10. Callout 转换 ✨新增

将文本中的提示语段自动重构为 Obsidian 原生 Callout 块。

> **只转换单独成段的提示语**，不碰正文中嵌入的强调文字。

**匹配规则：**

| 文本特征 | 转换为 |
|----------|--------|
| `注意` / `**注意**` / `Note:` | `> [!NOTE]` |
| `⚠️` / `警告` / `Warning:` | `> [!WARNING]` |
| `提示` / `💡` / `小技巧` / `Tip:` | `> [!TIP]` |
| `重要` / `关键` / `Important:` | `> [!IMPORTANT]` |
| `⚠️` + 危险内容 / `Danger:` | `> [!DANGER]` |

**示例：**
```
修复前：
**注意：** 此操作不可逆。

修复后：
> [!NOTE] 注意
> 此操作不可逆。
```

### 11. 标签智能提取 ✨新增

根据全文技术关键字，在顶部 Frontmatter 中自动追加相关 tags。

**约束：**
- **只追加，不删除、不改动**已有的 tags
- 只在用户确认后写入
- 从正文中提取 3-8 个最相关的技术关键词作为 tag
- tag 使用小写英文或简短中文

**常见映射：**

| 正文内容 | 建议 tag |
|----------|----------|
| C# / .NET | `csharp` |
| Python | `python` |
| SQL / 数据库 | `sql`, `database` |
| PLC / 工控 | `plc`, `automation` |
| 设计模式 | `design-patterns` |

### 12. 智能表情点缀 ✨新增

在适当位置插入 emoji，让笔记更生动易读。

> **适度原则**：emoji 是锦上添花，不是撒味精。一个 H2 标题最多 1 个，全篇保持克制。

**插入位置（优先级从高到低）：**

| 位置 | 示例 |
|------|------|
| H1 主标题 | `# 📦 数据类型` |
| H2 章节标题（核心章节） | `## 🔧 类型转换` |
| 列表中的分类项 | `- 🟢 装箱：值类型 → 对象类型` |
| Callout 标题 | `> [!TIP] 💡 小技巧` |

**不插入的位置：**
- H3 及更小的标题（太碎）
- 代码块内
- 正文段落中
- 表格内
- 已有 emoji 的位置（不重复加）

**场景映射：**

| 内容主题 | 推荐 emoji |
|----------|-----------|
| 数据结构、类型 | 📦 |
| 方法、函数、操作 | 🔧 |
| 关键字、语法 | 📝 |
| 原理、概念 | 💡 |
| 注意事项 | ⚠️ |
| 循环、迭代 | 🔄 |
| 条件、分支 | 🔀 |
| 错误、异常 | ❌ |
| 正确、成功 | ✅ |
| 对比、vs | 🆚 |
| 示例、演示 | 📌 |
| 总结、归纳 | 📋 |
| 继承、派生 | 🧬 |
| 转换、变换 | 🔀 |
| 输入输出 | 📥📤 |
| 内存、存储 | 💾 |

**处理流程：**
1. 先完成 1-11 所有格式化步骤
2. 扫描全文的 H1 和 H2 标题，匹配主题→推荐 emoji
3. 扫描列表中的分类项，匹配适合加 emoji 的行
4. **只加 3-8 个**，全篇最多不超过 10 个
5. 不确定时 → 不加

1. **读取文件**：完整读取目标 `.md` 文件
2. **逐项检查**：按上述 12 个步骤逐项检查问题
3. **分类报告**：告诉用户发现了哪些类型的问题，数量多少
4. **执行修复**：一次性写入修复后的完整文件
5. **总结变更**：用表格列出所有修改项

## 绝对不能改动的内容（白名单）

- **YAML frontmatter**：`---` 包裹的头部元数据（仅允许在用户同意下追加 tags）
- **Wiki 链接**：`[[xxx]]`、别名链接 `[[xxx|yyy]]` 和图片嵌入 `![[xxx]]`
- **Dataview 块**：```` ```dataview ```` 和 ```` ```dataviewjs ````
- **Mermaid 图表**：```` ```mermaid ````
- **笔记核心内容**：实际表达的知识、关键数据与结论
- 伪代码结构的教学注释（如 `// 字段、属性` 这种中文描述性注释）保留原意
- 中英混杂不确定的情况 → 宁可保持原样，不要改错