用途
yzr-md-to-html 用于把本地 Markdown 文件或目录转换成自包含、双击即可在浏览器打开的 HTML。典型对象包括 README、技术文档、笔记、论文草稿等。触发场景如“把这个 README 转成好看的 HTML 发给同事”。
主要能力
- 输入：一个 .md 文件，或一个目录（批量转换该目录下所有 *.md）。
- 输出：单个自包含 .html，CSS 与 Pygments 代码高亮全部内联；公式与图表按需渲染。
- 默认深色阅读主题（GitHub-dark 纯深色），带侧边栏目录与离线代码高亮。
- 公式与 Mermaid 按需联网：脚本检测到 $ 才挂 KaTeX CDN；Mermaid 默认转 ASCII（离线），只有转换失败或不支持的图类型（如 gantt、mindmap 等）才回退挂 Mermaid CDN。
- 支持自定义模板：通过 --template 传入 Jinja2 模板，可用变量包括 {{ content }}（正文 HTML）、{{ toc }}（目录 HTML）、{{ styles }}（默认主题 CSS）、{{ pygments_css }}（代码高亮 CSS）、{{ title }}、{{ lang }}，以及布尔开关 {{ has_math }} / {{ has_mermaid }} / {{ has_toc }}（控制是否挂对应 CDN / 侧边栏）。
- 文件输入默认生成同名 .html；目录输入默认就地生成；--title 默认取首个 # 一级标题，再退回文件名。
使用方式
前置条件：Python ≥ 3.7，无需 pandoc；依赖清单以 tools/md_to_html.py 的 DEPENDENCIES 常量为准，缺依赖时脚本会打印 pip install 命令。含 Mermaid 且未加 --no-mermaid-ascii 时另需 Node + beautiful-mermaid（缺时 wrapper 打印含版本号的 npm 安装命令，版本以 tools/mermaid_to_ascii.mjs 的 BEAUTIFUL_MERMAID_VERSION 为准）；不含 Mermaid 的文档不需要 Node。
参数与默认值以 python3 tools/md_to_html.py --help 为单一来源（argparse 定义）。脚本按自身路径定位 assets / wrapper，任意 cwd 可调用。
工作流：
- 确认输入 .md 路径（或目录）；首次使用确认依赖已装。
- 跑脚本： python3 tools/md_to_html.py <input.md> [-o <output.html>] 批量：把 <input.md> 换成目录路径即可。
- 把生成的 .html 路径告诉用户（双击即可浏览）。
- 脚本输出含公式 / Mermaid 回退需联网的通知时，原样转达用户。
- 上传 / 分享（可选）：产物本是本地自包含文件、不需要上传；用户要分享且 agent 已配置 agent-html-drop MCP 时，调用其上传工具推 .html 即可——不提供其他上传方式；未配置就把本地路径交给用户。
样例：
- 单篇技术文档：python3 tools/md_to_html.py docs/design.md → 生成 docs/design.html：深色主题 + 侧边栏目录 + 代码高亮。
- 批量转换整个目录：python3 tools/md_to_html.py notes/ → notes/ 下每个 .md 就地生成同名 .html。
适用场景
- 把单篇 README / 技术文档 / 笔记 / 论文草稿转成便于分享的 HTML。
- 批量把某个目录下的 Markdown 全部转成 HTML。
- 需要公式或 Mermaid 图表正常呈现的文档。
- 希望自定义模板与主题风格的场景。
限制
- 一次一份或一次一目录，不做跨文档合并；多份想合成一个 HTML 需先拼成一个 .md。
- 直接跑脚本，不自创 HTML：转换逻辑、主题、CDN 挂载都在 tools/md_to_html.py，agent 不要现场拼 HTML 或现写 markdown 库调用。
- 不要无脑给所有文档挂全套 CDN（普通 README 不该背公式 / 图表的网络请求与加载耗时）。
- ASCII 转换可关：不想转 ASCII 时用 --no-mermaid-ascii 强制走 Mermaid CDN。
- 上传 / 分享仅支持已配置的 agent-html-drop MCP，不提供其他上传方式（不经 rsync 推 server、不写部署配置）。
- 具体收费、价格、平台等信息暂未提供。