sn-md-to-html-report

Markdown 转 HTML 报告

默认目标

生成“长篇研究报告阅读版”HTML：正文舒展、图片自然插入、表格清晰、目录可用、可离线打开。优先保持内容可信和阅读舒服，不做营销页、不做炫技页面。

推荐路径

优先使用内置脚本生成稳定结果：

python3 /path/to/sn-md-to-html-report/scripts/render_report.py input.md output.html

常用参数：

• --embed-images：将本地图片嵌入 HTML，适合单文件分享。默认开启。
• --no-embed-images：保留相对图片路径，适合文件夹整体发布。
• --with-js：加入阅读进度、目录高亮、返回顶部等轻量交互。
• --keep-inline-toc：保留 Markdown 正文中已有的目录；默认会移除正文目录，避免和侧边栏目录重复。
• --mermaid-source auto|cdn|local|none：渲染 Markdown 中的 Mermaid 代码块。默认 auto，检测到 ```mermaid 代码块时使用 CDN；local 会引用输出 HTML 同目录下的 mermaid.min.js；none 保留为普通代码块。
• --title-style comfortable：默认舒适报告模板。

生成后运行图片检查：

python3 /path/to/sn-md-to-html-report/scripts/check_image_refs.py output.html

当输出使用 --embed-images 时，检查结果中的本地图片引用数通常为 0，这是正常的。

工作流程

1. 确定输入 Markdown 和输出 HTML。
   • 用户只给输入路径时，在同目录生成同名 .html。
   • 若同名 HTML 已存在，优先换新文件名，除非用户明确要求覆盖。
2. 转换前检查 Markdown。
   • 以 Markdown 所在目录作为相对图片基准。
   • 将误用的全角表格竖线 ｜ 修正为半角 |，避免表格错列。
   • 对“说明文字：”后紧跟 -、* 或数字编号列表但中间缺空行的常见写法，转换前补空行，让分点输出渲染为真正列表。
   • 如果 Markdown 已有 ## 目录 且内容是章节锚点列表，默认从正文中移除；侧边栏目录已经提供导航，正文目录会重复占空间。
   • 保留原文内容，不总结、不改写、不新增事实。
3. 生成完整 HTML5。