📦 format-markdown-mkdocs — Markdown 格式化与 MkDocs 兼容性修复

具有两层处理功能的 Markdown 格式化技能：

• 内容格式化：分析内容，提高可读性，并在需要时添加元数据或结构辅助。
• 结构兼容性修复：为数学公式、列表和表格块应用 mkdocs/material 安全的间距修复，而不重写文本内容。

您必须遵循下方 工作流程 部分中的工作流程，不得跳过任何必需步骤。

核心原则

• 尽可能保留原始含义和措辞。
• 在内容格式化模式（步骤 2-5）中，可以添加元数据和结构辅助，例如标题、摘要、标题、强调、列表、表格和警告框。
• 在步骤 6 结构修复模式中，脚本仅执行空白字符更改，绝不重写文本内容。

使用方法

工作流程有两个阶段：

• 分析和格式化内容（步骤 1-5）
• 应用结构兼容性修复，以支持 mkdocs/material 渲染（步骤 6）

Claude 首先执行内容分析和格式化，然后将结构兼容性脚本作为最终清理步骤运行。

工作流程

步骤 1：读取并检测内容类型

读取用户指定的文件，然后检测内容类型：

检测到现有的 markdown 格式。您想怎么做？
优化格式（推荐）- 分析内容，改进标题、粗体、列表、表格和可读性
   
- 之后运行结构兼容性脚本
   - 输出：{filename}_formatted.md
保持原始格式 - 保留现有的 markdown 结构
   
- 仅在复制的文件上运行结构兼容性脚本
   - 输出：{filename}_formatted.md
仅进行结构修复 - 直接在原始文件上运行结构兼容性脚本
   
- 不创建副本；直接修改原始文件

根据用户选择：

• 优化：继续步骤 2（完整工作流程）
• 保持原始：跳到步骤 5，复制文件，然后运行步骤 6
• 仅结构修复：跳到步骤 6，直接在原始文件上运行

Typos Found - [list any obvious typos with corrections, or "None found"]

---

Step 3: 检查/创建 Frontmatter、标题和摘要

检查 YAML frontmatter（--- 块）。如果缺失则创建。

标题生成

无论标题是否已存在，始终运行标题优化流程，除非设置了 auto_select_title。

准备工作 — 阅读完整文本并提取：

• 核心论点（一句话："这篇文章是关于什么的？"）
• 最有影响力的观点或结论
• 读者的痛点或好奇心触发点
• 最令人难忘的比喻或金句

生成 3-4 个风格差异化的候选标题：

Pick a title:
[Title A] — (recommended)
[Title B] — [style note]
[Title C] — [style note]
Enter number, or type a custom title:

将最强的钩子放在第一位并标记为推荐。

标题原则：

• 前 5 个字符内设置钩子：制造信息缺口或认知冲突
• 具体 > 抽象："150 lines" 优于 "a document"
• 否定 > 肯定："you're doing it wrong" 优于 "the right way"
• 会话式：像和朋友聊天，而不是写论文标题
• 最多约 25 个字符：较长的标题在信息流中会被截断
• 准确，不做标题党：文章必须兑现标题的承诺

禁止的模式：

• "浅谈 XX"、"关于 XX 的思考"、"XX 的探索与实践"
• "震惊！"、"万字长文"、"建议收藏"
• 没有方向性的纯问题："AI 写作的未来在哪里？"

如果 frontmatter 中存在 title 且正文内容中没有 H1，你必须将标题作为第一个 H1 插入（# {{title}}）。不要删除它。

如果 frontmatter 已有 title，将其作为上下文包含，但仍需生成新的候选标题，除非配置允许跳过。

摘要生成

从不同角度生成 3 个候选摘要。呈现给用户：

Pick a summary:
[Summary A] — [focus note]
[Summary B] — [focus note]
[Summary C] — [focus note]
Enter number, or type a custom summary:

摘要原则：

• 80-150 个字符，精确且信息丰富
• 传达对读者的核心价值，而不仅仅是主题
• 角度多样化：问题驱动型、结果驱动型、洞察驱动型
• 吸引读者：让他们想阅读完整文章
• 使用具体细节（数字、结果、特定方法）而非模糊描述

禁止的模式：

• "本文介绍了..."、"本文探讨了..."
• 纯主题描述，没有价值主张
• 用不同措辞重复标题

如果 frontmatter 已有 summary，跳过选择环节，直接使用它。

为了让摘要可见显示，请按照警告语法规则生成它。将其放在 H1 标题之后：

!!! example "Summary"
    Here is the summary you generated.

EXTEND.md 跳过行为：

如果 EXTEND.md 中设置了 auto_select: true，跳过标题和摘要选择，直接生成最佳候选而不询问用户。用户也可以独立设置 auto_select_title: true 或 auto_select_summary: true。

Step 4: 格式化内容

根据 Step 2 的分析指导进行格式化。目标是使内容易于扫描，关键要点易于理解。

格式化工具包

警告语法规则

严格强制执行。当使用 MkDocs 风格的警告框（如 !!! note、!!! example、!!! warning）时，必须严格遵循这些缩进规则。Markdown 解析器要求块内的内容必须缩进。

正确的格式：

!!! note "Title Text"
    This is the content. It must start with 4 spaces, and the above line is empty.
    This is a second paragraph. It also needs 4 spaces indentation.
    - List items also follow.
    The end line should have an empty line with no indent below.
This is the line outside admonition (correct).

错误的格式（请勿这样做）：

!!! note "Title Text"
This content has no indent. (Wrong - breaks indentation rule)
!!! note "Title Text"
First paragraph ok.
Second paragraph has no indent. (Wrong - breaks the block)

语法规则：

• 缩进：属于警告框的所有内容必须相对于 !!! 行缩进 4 个空格。
• 段落分隔：块内的空行也必须保持块结构；确保下一段以 4 个空格开头。
• 嵌套列表/代码：如果在警告框内使用列表或代码，总共缩进 8 个空格。
• 一致性：不要混合制表符和空格。始终使用 4 个空格。

格式化原则 — 不要做什么

• 不要添加编造的事实、解释或评论
• 不要在用户未明确要求的情况下删除或缩短有效的原始内容
• 除非任务明确要求，否则不要改写或重写作者的措辞
• 不要添加带有主观评价的标题（例如 "Amazing Discovery"）；使用中性的描述性标题
• 不要过度格式化：不是每个句子都需要粗体，也不是每个段落都需要标题

格式化原则 — 应该做什么

• 尽可能保留作者的 voice、tone 和措辞
• 将关键结论和核心要点加粗——读者可能会高亮的句子
• 当结构清晰时，将散文中的并列项提取为列表
• 在话题真正转换的地方添加标题
• 将散文中埋藏的比较或结构化数据使用表格
• 将金句、令人难忘的声明或重要警告使用引用块
• 仅在修正明确无误时修复明显的拼写错误

Step 5: 保存格式化文件

将格式化内容保存为新文件。输出文件名由原始文件名加上 EXTEND.md 中定义的后缀组成。

• 默认后缀：_formatted → {original-filename}_formatted.md
• 通过 EXTEND.md 覆盖：设置 output_suffix: _formatted → {original-filename}_formatted.md

覆盖前备份现有文件：

if [ -f "{filename}_formatted.md" ]; then
    mv "{filename}_formatted.md" "{filename}_formatted.backup-$(date +%Y%m%d-%H%M%S).md"
fi

Step 5 保存格式化文件后，Step 6 必须在该保存的输出文件上原地运行。

Step 6: 执行结构渲染兼容性脚本

脚本存储在 scripts/ 子目录中。${SKILL_DIR} 是包含此 SKILL.md 的根目录。

此脚本专为 MkDocs + Material 渲染兼容性设计。它修复数学公式、列表和表格块周围的结构间距，同时保留文档内容。

运行时要求

• Node.js 18+
• 在 ${SKILL_DIR} 中一次性安装本地 npm 依赖

如果尚未安装依赖：

cd ${SKILL_DIR}
npm install

如果 package-lock.json 已存在，优先使用：

cd ${SKILL_DIR}
npm ci

脚本执行

node ${SKILL_DIR}/scripts/format-md.js "${output_file}"

其中 ${output_file}` 是 Step 5 中保存的格式化文件的路径。

脚本将：

• 读取输出文件
• 应用 MkDocs + Material 兼容性修复：

• 将修改后的内容写回同一文件

Step 7: 最终检查与输出

完成所有格式化步骤后，进行最终检查：

• [ ] YAML frontmatter 完整且格式正确
• [ ] 标题已生成并呈现给用户选择
• [ ] 摘要已生成并按要求显示
• [ ] 所有格式化元素正确应用
• [ ] 警告框语法正确
• [ ] 文件已保存到正确位置
• [ ] 结构渲染兼容性脚本已执行

向用户报告完成状态和输出文件位置。

📋 步骤 7：完成报告

格式化完成
文件：
分析报告：{filename}-analysis.md
格式化文件：{filename}_formatted.md
内容分析摘要：
发现亮点：X 个关键见解
精彩引用：X 个令人难忘的句子
修复的格式问题：X 项
应用的更改：
Frontmatter：[已添加/已更新]（标题、slug、摘要）
添加的标题：X 个（##: N，###: N）
添加的粗体标记：X 个
创建的列表：X 个（从散文转换为列表）
创建的表格：X 个
添加的警告提示：X 个
修复的拼写错误：X 个 [逐项列出："原内容" → "正确内容"]
结构兼容性脚本：
处理的数学块：X 个
处理的列表块：X 个
处理的表格块：X 个
添加的空行：X 个
移除的数学内部空行：X 个
创建备份：[是/否]