背景与起因
这是一个我自用的 Claude Code 小 Skills。阅读原文可跳转到部署🔗。
首先依然是说一下为什么要做这个。
我日常在网站发布笔记，流程如下：
写成 markdown 文件 -> mkdocs （框架） -> material （风格） -> github workflow/ pages （CICD，部署发布）。
理论上，只要做一些和 mkdocs 框架与 mkdocs materials 相适配的格式调整，即可发布到我的网站上了。但是，mkdocs material 支持一些特殊且好用的markdown语法，并且有些地方的规则与默认markdown稍有不同。试举几例：
段落公式必须与前后段之间空行，否则会渲染出错，同时段落公式内不允许在开头结尾有冗余的空行，i.e., 对于如下若干格式，只有最后一种能被正确渲染：
"Case. 1(❌)"
这是我的第一行。
$$E = mc^2$$
这是我的第二行。
"Case. 2(❌)"
这是我的第三行。
\[E = mc^2\]
这是我的第四行。
"Case. 3(❌)"
这是我的第三行。
\[
E = mc^2
\]
这是我的第四行。
"Case. 4(✅)"
这是我的第五行（⬇️终于正确版）。
\[E = mc^2\]
这是我的第四行（⬆️终于正确版）。
上述代码实际渲染效果如下：
对于列表、有序列表、表格，必须与前后段落之间保持空行，否则渲染会黏连在一起。
"Case. 1(❌)"
这是列表前的第一句话。
- 这是第一点。
- 这是第二点。
- 这是第三点。
这是列表后的第一句话。
"Case. 2(❌)"
这是列表前的第一句话。
* 这是第一点。
* 这是第二点。
* 这是第三点。
这是列表后的第一句话。
"Case. 3(✅)"
这是列表前的第一句话。
- 这是第一点。
- 这是第二点。
- 这是第三点。
这是列表后的第一句话。
"Case. 4(❌)"
这是表格前的第一句话。
| Col1 | Col2 |
| :---: | :---: |
| (1,1) | (1,2) |
| (2,1) | (2,2) |
| (3,1) | (3,2) |
这是表格后的第一句话。
"Case. 5(✅)"
这是表格前的第一句话。
| Col1 | Col2 |
| :---: | :---: |
| (1,1) | (1,2) |
| (2,1) | (2,2) |
| (3,1) | (3,2) |
这是表格后的第一句话。
上述代码实际渲染效果如下：
此外，mkdocs material 有一些高度定制化的语法，比如 Admonition，header 与正文之间需要有 4-indent 的缩进。
!!! note "This is header."
This is contents.
我发现从各个地方复制过来的 markdown 文本、以前写过的笔记，往往会在很多不经意的角落里，违背这几个准则。我一开始以为可以通过 mkdocs material 的某些默认配置，实现对这几种情况的兼容，但是查阅资料并没有找到证据。同时，上述写法在官方的文档中也是首先采用的。
一方面，这种格式的修改很让我头疼。考虑到一个300～400行的精修笔记可能有几十处公式，十余处表格，手动进行调整让我觉得效率低下。
另一方面，这个小问题的存在导致 markdown 的直接可交付性被极大削弱了。我不喜欢这种高度不确定性。
我希望我的Skills能自动把一些内容整理成这个格式的样子，不出格式错误。
实现
在实现过程中，深度参考了宝玉老师的 baoyu-format-markdown，基础框架只做了一些微调，保留了文章总结功能，剔除更换了 js 脚本：
在我的实现中，会有一个脚本自动提取markdown文件的 AST（抽象语法树），这样我可以灵活地检索控制具体的代码块所属的类别（表格、bullet point、公式），然后对于不符合条件的格式进行前后添加空行等操作； 严格保证文本一致性。除了调整格式之外，不对原文做任何操作； 流程参数化，可以选择： 是否进行总结 是否运行脚本 单独运行脚本不做其他
这是一个小 Skill，目的是对我计划发布到网站的 .md 文件进行最后一次处理，对格式进行严格的微调以适应渲染的要求，最终会返回我修改的结果。
结果
放一组输出的markdown文件及渲染结果。图中所有内容均未经过人工调整。
"Before (表格渲染错误，公式缩成行内)"
"After (理想的干净形式)"
以及：
"Before (表格渲染错误，公式缩成行内)"
"After (理想的干净形式)"
还有：
"Before (表格渲染错误，公式缩成行内)"
"After (理想的干净形式)"
运行中间会自动生成中间文件、生成分析文件和备份。目录如下：
./docs/Study/Statistics
├── AdvancedStatistics
│ └── class1.md
├── example-analysis.md. # analysis
├── example.md # original
├── example_formatted.md # final
└── example_formatted.md.backup-2026-03-24T07-47-38.md # backup
最终会输出一份调整报告：
使用
可以在 ClawHub 的这个🔗 使用。
