原始文章的样式
原始文字的样式
没有什么特别的,就是普普通通的 markdown 格式,没有扩展。这也是我之所以要花费力气写转换脚本的原因,我不希望为了样式而去牺牲实用性和便捷性。
Hexo 要求文章的标题上方用横线,mkdocs 有各种各样的额外语法,但是这些都不能被普通的渲染器正确渲染。我以前用 hexo 搭建时用了许多它的语法,所以导致有的时候迅速本地看一篇文章时渲染格式不对,所以没有必要这样。就用最普通的方式,然后用转换脚本去优化它,比如原始文章使用中文括号作为强调,那么转换脚本会将其转换为 <em> 标签。
转换流程及细节
main.py 使用流水线方式串联步骤:
| 步骤 | 脚本 | 作用 |
|---|---|---|
| 01 | repair_src_links.py |
修复源目录链接,处理文件改名/路径变化导致的失效引用(基于文件 ID 查找)。 |
| 02 | base_build.py |
执行主转换流程,遍历源目录并生成目标文件,同时更新缓存以支持增量构建。 |
| 03 | sync_file_actions.py |
同步缓存页面的“本地编辑 / 复制路径”入口。 |
| 04 | postprocess_dst_mds.py |
后处理目标 Markdown 格式(列表、details、公式、箭头等)。 |
| 05 | repair_dst_links.py |
修复目标 Markdown 中的引用链接,将资源链接对齐到目标目录。 |
| 06 | build_links.py |
为 Windows 快捷方式生成站内页面副本。 |
| 07 | delete_unnecessary_files.py |
清理失效转换结果与不再引用的资源。 |
| 08 | compress_images.py |
压缩 JPG/PNG 图片资源。 |
| 09 | gen_archive.py |
生成归档页面。 |
| 10 | gen_navbar.py |
按目录名、文件名和 .pages 顺序生成导航,不解析正文标题。 |
| 11 | check_single_index.py |
报告仅含 index.md 的目录。 |
| 12 | write_asset_rawdir.py |
在 asset 子目录写入 rawdir.txt,记录原始文件路径。 |
| 13 | report_asset_sizes.py |
统计 asset 目录大小。 |
| 14 | delete_unnecessary_files.py |
再次执行收尾清理。 |
| 15 | copy_overrides.py |
同步站点脚本、样式、字体和模板。 |
日常使用 UpdateBlog 做增量构建;它会先检查环境,只运行一次上面的内容流水线,再分别生成手机端和 Web 端。转换脚本变化而源文件未变化时,使用 UpdateBlog --rebuild 显式全量转换;只想检查环境时使用 UpdateBlog --doctor-only。