原始文章的样式
复制本地路径 | 在线编辑
原始文字的样式
没有什么特别的，就是普普通通的 markdown 格式，没有扩展。这也是我之所以要花费力气写转换脚本的原因，我不希望为了样式而去牺牲实用性和便捷性。
Hexo 要求文章的标题上方用横线，mkdocs 有各种各样的额外语法，但是这些都不能被普通的渲染器正确渲染。我以前用 hexo 搭建时用了许多它的语法，所以导致有的时候迅速本地看一篇文章时渲染格式不对，所以没有必要这样。就用最普通的方式，然后用转换脚本去优化它，比如原始文章使用中文括号作为强调，那么转换脚本会将其转换为 <em> 标签。
转换流程及细节
main.py 使用流水线方式串联步骤：
| 步骤 | 脚本 | 作用 |
|---|---|---|
| 01 | repair_src_links.py |
修复源目录链接，处理文件改名/路径变化导致的失效引用（基于文件 ID 查找）。 |
| 02 | base_build.py |
执行主转换流程，遍历源目录并生成目标文件，同时更新缓存以支持增量构建。 |
| 03 | delete_unnecessary_files.py |
清理生成目录中的多余文件（含失效转换结果与不再使用的资源）。 |
| 04 | postprocess_dst_mds.py |
后处理目标 Markdown 格式（列表、details、箭头等），提升 mkdocs 渲染效果。 |
| 05 | repair_dst_links.py |
修复目标 Markdown 中的引用链接，将资源链接对齐到目标目录。 |
| 06 | compress_images.py |
压缩图片资源（jpg / png 分别处理），减少体积且尽量避免改动链接后缀。 |
| 07 | gen_archive.py |
生成归档页面。 |
| 08 | gen_navbar.py |
生成侧边栏导航结构。 |
| 09 | check_single_index.py |
检查生成目录中“仅含 index.md”的目录，避免最终展示突兀。 |
| 10 | write_asset_rawdir.py |
在 asset 子目录写入 rawdir.txt，记录原始文件路径，便于追溯。 |
| 11 | report_asset_sizes.py |
统计 asset 目录大小。 |
| 12 | delete_unnecessary_files.py |
再次执行收尾清理。 |