一、为什么要转换格式
如果你想把一篇外部文章——比如从别的博客、公众号、知乎、Markdown 笔记里复制来的内容——发布到超米站点（cm.zy1080.xyz），直接粘贴往往会遇到三个问题：文章没有目录导航、标题没有锚点跳转、排版和站内既有文章不一致。
这是因为超米站点的文章有一套固定的格式约定。只要掌握这套约定，并借助一个小工具，就能把任何外部文章一键转换成网站可用的格式，几分钟内完成发布。本文就详细讲解这套格式约定、转换工具的使用方法，以及发布的全过程。
二、网站文章的格式约定
在动手转换之前，必须先理解站点文章长什么样。超米站点的文章由三部分组成：目录块、带锚点的标题、正文段落。下面逐一说明。
2.1 目录块
每篇文章的开头（正文主章节之前）都有一段目录块，它是一个 Gutenberg 区块注释，格式固定为：
<!-- wp:cm-geek/toc {"title":"本文目录","depth":2} /-->
几个必须注意的细节：
- 区块名是
cm-geek/toc，注意是斜杠命名空间，不是wp:cm-toc。 - 属性
title是目录标题，默认填本文目录；depth是目录深度，2表示提取 h2 和 h3 两级标题，3则额外包含 h4。 - 这段注释在渲染时会被站点的目录服务端函数识别，自动扫描正文里的 h2、h3 标题，生成带锚点的目录列表，同时桌面端显示侧栏目录、移动端显示浮窗”目录”按钮。
2.2 标题锚点
正文里的每个 h2、h3 标题都必须带一个 id 属性，作为目录跳转的锚点。这个 id 使用拼音，多个字之间用连字符连接，例如：
<h2 id="yi-yinyan">一、引言</h2>
<h3 id="1-1-xiaojie">1.1 小节</h3>
<h2 id="er-jielun">二、结论</h2>
规律是：中文转拼音、数字和英文字母原样保留、标点符号（顿号、冒号、点号）全部替换成连字符 -、整体转小写。如果标题里已有 id，则保留不覆盖。
2.3 段落与元信息
正文段落用标准的 <p> 标签，表格用 <figure class="wp-block-table"> 包裹。同时有两点要特别注意：
- 正文里不要再写文章标题（h1 会由站点主题根据文章标题自动渲染）。
- 正文里不要手写”作者””分类””日期”这些信息——它们由 WordPress 的文章作者、分类、发布时间元数据自动承担，写在正文里反而会重复。
三、转换工具：cm-import.py
为了省去手工转换的麻烦，站点准备了一个转换脚本 cm-import.py，它封装了上面所有格式约定，一条命令完成”识别 + 转换 + 发布”。
3.1 准备环境
脚本依赖两个 Python 库：pypinyin（拼音转换）和 markdown（Markdown 渲染）。在 Python 虚拟环境里安装：
pip install pypinyin markdown
3.2 三种输入方式
脚本支持三种输入来源，对应三种常见场景：
- 外部 URL：
--url参数，脚本会自动抓取网页、识别标题和正文，提取 h2/h3/p 等结构化内容。 - 本地文件：
--file参数，支持 Markdown（.md）和 HTML 两种文件。 - 直接文本：
--text参数，把内容直接作为参数传入。
四、转换步骤详解
下面按三种输入方式，逐步说明完整的转换流程。
4.1 从外部 URL 抓取
第一步，执行抓取命令：
python cm-import.py --url https://example.com/article
脚本内部会做几件事：用标准 HTTP 客户端抓取页面，优先识别 <article> 或 <main> 标签里的正文，剔除脚本、样式、导航、页脚等干扰内容，然后提取 h2、h3、p 等结构化标签，并自动读取网页标题。抓取完成后会打印识别出的标题和转换后的 HTML 长度，供你确认。
第二步，如果抓取结果正确，加上发布参数直接发布（下一节说明）；如果不正确，建议改用 --file 或 --text 手动整理内容后再转换。
4.2 从 Markdown 转换
这是最常用的方式。把文章保存为 .md 文件，例如 article.md，内容用 Markdown 的 #、##、### 表示标题层级。执行：
python cm-import.py --file article.md
脚本会做这些处理：去掉第一行的 # 一级标题（因为文章标题由站点单独设置），去掉 **作者**、**分类**、**日期** 这类元信息行，然后把 ## 和 ### 分别转成带拼音锚点的 <h2>、<h3>，并在正文前插入目录块。
4.3 从纯文本转换
如果只有零散的文本，用 --text 参数传入，并额外指定标题：
python cm-import.py --text "## 引言 ..." --title "文章标题"
文本里依然可以用 ##、### 标记标题层级，脚本会按 Markdown 规则处理。
五、发布到网站
转换完成后，进入发布环节。
5.1 直接发布
在转换命令后追加 --publish 参数，并指定分类和作者，即可一步完成转换并发布：
python cm-import.py --file article.md --publish --category 1 --author 2
其中 --category 1 表示发布到”杂谈”分类，--author 2 表示作者为 deepseek。站点常用的分类编号是：1 为杂谈、4 为 DeepSeek；作者编号 2 为 deepseek、1 为站点管理员。
发布成功后，脚本会输出文章的 ID 和正式访问链接，打开链接即可看到带目录、带锚点的完整文章。
5.2 先预览再发布
如果想先看转换结果、确认无误再发布，可以先不加 --publish，只做转换，用 --out 把结果写到文件检查：
python cm-import.py --file article.md --out preview.html
确认 preview.html 里的目录块、拼音锚点、段落格式都正确后，再加上 --publish 正式发布。
六、常见问题与注意事项
这一节汇总容易踩坑的几个点，务必留意。
6.1 目录块格式不能写错
目录块必须是 <!-- wp:cm-geek/toc {...} /--> 这样的区块注释。如果误写成普通 HTML（比如手写一个 <nav class="cm-toc"> 占位标签），虽然目录也可能被服务端识别，但不符合站点标准，后续维护和编辑器识别都会出问题。使用 cm-import.py 会自动生成正确格式，无需手写。
6.2 标题锚点用拼音
锚点 id 一定要用拼音，否则目录跳转的锚点会变成中文，和站内既有文章不一致。规律是”中文转拼音、标点转连字符、整体小写”。cm-import.py 已经内置了这套转换，直接使用即可。
6.3 敏感信息必须脱敏
如果外部文章里包含真实的 IP 地址、密钥、密码、Token 等敏感信息，发布前一定要做脱敏处理。例如 IP 地址保留前三段、隐藏主机位（192.168.1.***），密钥和 Token 用 *** 或占位符代替。这一步不能省略，否则会造成信息泄露。
6.4 元信息交给站点
不要在正文里重复写”作者””分类””日期”。这些信息通过发布时的 --author、--category 参数，以及 WordPress 的发布时间自动体现，正文里只保留真正的文章内容。
七、总结
把外部文章转换为网站文章，核心就三步：理解格式约定（目录块 + 拼音锚点 + 段落）、用 cm-import.py 完成转换、加 --publish 发布。掌握了这套流程，任何来源的文章都能在几分钟内变成一篇排版规范、带目录导航的站内文章，彻底告别手工调整格式的麻烦。