yzr95924 把一份本地 Markdown 转成自包含、双击即可在浏览器浏览的 HTML 文件。默认套一套
深色阅读主题（GitHub-dark 风格，纯深色），自带侧边栏目录 TOC、离线代码
语法高亮（Pygments），并按需自动启用数学公式（KaTeX）与 Mermaid 图表：只有源文件
里真出现 $ 才会挂 KaTeX CDN；Mermaid 代码块默认转成 ASCII 图离线渲染（无需联网），
只有转换失败 / 不支持的图类型才回退到 Mermaid CDN。普通文档零额外网络请求。
输入 / 输出
- 输入：一个
.md文件，或一个目录（批量转该目录下所有*.md） - 输出：单个自包含
.html（CSS 与 Pygments 高亮全部内联，公式 / 图表按需渲染） - 参数与默认值以
python3 scripts/md_to_html.py --help为单一来源（argparse 定义，此处不 重抄）：文件输入默认生成同名.html；目录输入默认就地生成，--title默认取首个#一级标题再退回文件名
自定义模板可用变量（--template 传入的 Jinja2 模板里用，不在 --help 范围内）：
{{ content }}（正文 HTML）、{{ toc }}（目录 HTML）、{{ styles }}（默认主题 CSS）、
{{ pygments_css }}（代码高亮 CSS）、{{ title }}、{{ lang }}，
以及布尔开关 {{ has_math }} / {{ has_mermaid }} / {{ has_toc }}（控制是否挂对应 CDN / 侧边栏）。
执行原则 / 边界
- 直接跑脚本，不自创 HTML：转换逻辑、主题、CDN 挂载都在
scripts/md_to_html.py， agent 不要现场拼 HTML 或现写 markdown 库调用——保证产物一致、主题统一、扩展行为可预期 - 按需挂 CDN：脚本检测到
$才挂 KaTeX CDN；Mermaid 默认转 ASCII（离线），只有 转换失败 / 不支持的图类型（gantt / mindmap 等）才回退挂 Mermaid CDN； 不要无脑给所有文档挂全套 CDN（普通 README 不该背公式 / 图表的网络请求与加载耗时） - 深色主题默认：默认 GitHub-dark 纯深色；
要彻底换风格走
--template/--style - 一次一份或一次一目录：不做跨文档合并；多份想合成一个 HTML 请先拼成一个
.md - ASCII 转换可关：不想转 ASCII 时用
--no-mermaid-ascii强制走 Mermaid CDN
工作流 / 步骤
1. 确认输入 .md 路径（或目录）；首次使用确认依赖已装（见前置条件）
2. 跑脚本：
python3 yzr-md-to-html/scripts/md_to_html.py <input.md> [-o <output.html>]
批量：把 <input.md> 换成目录路径即可
3. 把生成的 .html 路径告诉用户（双击即可浏览）
4. 提醒联网事项：源文档含公式时首次打开需联网加载 KaTeX CDN；有 Mermaid 块转 ASCII
失败回退 CDN 时同理需联网（全部转成功则完全离线）
上传产物（agent-html-drop MCP）
转换得到的 .html 是本地自包含文件，双击即可在浏览器打开，本身不需要上传。
若用户想把产物上传 / 分享出去，仅当 agent 已配置 agent-html-drop MCP 服务时才考虑上传——
直接调用该 MCP 提供的上传工具把 .html 推上去即可。当前不提供其他上传方式（不经 rsync 推
server、不写部署配置）；agent-html-drop 未配置时，把本地 .html 路径交给用户自行处理。
参考样例
样例一：单篇技术文档（最常见）
python3 yzr-md-to-html/scripts/md_to_html.py docs/design.md
# → 生成 docs/design.html：深色主题 + 侧边栏目录 + 代码高亮
样例二：带公式和流程图的论文草稿
python3 yzr-md-to-html/scripts/md_to_html.py draft.md -o draft.html
# draft.md 含 $E=mc^2$ 与 mermaid 块 → 产物公式走 KaTeX CDN、mermaid 转 ASCII 离线渲染
样例三：批量转换整个目录
python3 yzr-md-to-html/scripts/md_to_html.py notes/
# → notes/ 下每个 .md 就地生成同名 .html
前置条件
Python ≥ 3.7，无需 pandoc
Python 依赖清单的单一来源：
scripts/md_to_html.py的DEPENDENCIES常量直接跑脚本即可；缺 Python 包时脚本报错并列出
pip install命令（不抛裸 ImportError 栈）含 Mermaid 且未用
--no-mermaid-ascii时需 Node +beautiful-mermaid（npm 包）。 首次使用执行（<skill目录>为 skill 实际安装位置）：npm install beautiful-mermaid --prefix <skill目录>版本以
scripts/mermaid_to_ascii.mjs的BEAUTIFUL_MERMAID_VERSION常量为准； 缺依赖时脚本会打印含版本号的完整安装命令。不含 Mermaid 的文档完全不需要 Node