# Format JSON

> 将 Markdown 代码块中未格式化的 JSON 格式化为标准的美化 JSON。何时使用：当用户需要美化 .md 文件中的 JSON 数据或要求格式化 JSON 代码块时。

- Skill: `steelan9199/format-json` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add steelan9199/format-json`
- Raw SKILL.md: https://api.skillmd.com/api/skills/steelan9199/format-json/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: steelan9199 (https://skillmd.com/u/steelan9199)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/steelan9199/format-json

---


# Format JSON in Markdown

## 功能概述

本 Skill 用于扫描 Markdown 文件中的代码块，自动将其中未格式化（压缩成一行）的 JSON 数据转换为标准缩进格式（2 空格），使其易于人类阅读。支持 ` ``` `、` ```json ` 等任意语言标识的代码块；只要代码块内容能被 `JSON.parse()` 成功解析，就会自动美化，解析失败则保持原样不变。

## 环境说明

- 本 Skill 的脚本 `format-json.js` 与 `SKILL.md` 位于同一目录。
- 下文以 `<skill-dir>` 指代该目录（即 skill 的安装目录）。

## 执行步骤

| 步骤 | 动作           | 命令/操作                                         |
| ---- | -------------- | ------------------------------------------------- |
| 1    | 获取目标文件   | 确定用户指定的 `.md` 文件路径；如未指定，询问用户 |
| 2    | 运行格式化脚本 | 执行 `node <skill-dir>/format-json.js <文件路径>` |
| 3    | 确认执行结果   | 检查控制台是否输出 "JSON 格式化完成"              |
| 4    | 向用户反馈     | 报告格式化完成，并展示变更后的 JSON 代码块        |

## 决策逻辑

| 条件                      | 执行动作                            |
| ------------------------- | ----------------------------------- |
| 用户指定了 `.md` 文件路径 | 直接运行脚本                        |
| 用户未指定文件路径        | 询问用户需要格式化的 `.md` 文件路径 |
| 脚本执行失败              | 按【脚本说明】手动执行格式化步骤    |

## 脚本说明

本 skill 目录下附带脚本 [format-json.js](format-json/format-json.js)，逻辑如下：

1. 读取目标 `.md` 文件内容。
2. 正则匹配所有代码块：`(```(?:\w+)?\n)([\s\S]*?)(\n```)`。
3. 对每个代码块内容执行 `trim()`，去除前后空白字符（包括空行）。
4. 尝试 `JSON.parse()` 解析。
   - 成功：替换为 `JSON.stringify(parsed, null, 2)`。
   - 失败：保留原样。
5. 将结果写回原文件。

## 错误处理

| 错误场景              | 处理方式                                               |
| --------------------- | ------------------------------------------------------ |
| 文件不存在            | 检查路径是否正确，提示用户提供正确的 `.md` 文件路径    |
| 脚本执行失败          | 检查 Node.js 环境；如环境问题则按【脚本说明】手动执行  |
| 未找到可格式化的 JSON | 向用户说明文件中不存在可被 `JSON.parse()` 解析的代码块 |

## 示例

### Before

````markdown
```json
{ "users": [{ "name": "Alice", "age": 30 }], "count": 1 }
```
````

### After

````markdown
```json
{
  "users": [
    {
      "name": "Alice",
      "age": 30
    }
  ],
  "count": 1
}
```
````