yzr-md-to-html

yzr-md-to-html

Convert local Markdown intoself-contained, double-click to browseHTML: dark reading theme + sidebar table of contents + offline code highlighting, formulas / Mermaid only connect to the network on demand (for the full specification see Execution Principle 2)

Input and Output

• Input: one .md file, or one directory (batch convert all *.md）
• Output: a single self-contained .html(CSS and Pygments highlighting are all inlined; formulas / diagrams are rendered on demand)
• Parameters and default values use python3 tools/md_to_html.py --help as the single source of truth(defined by argparse, not repeated here); the script locates assets / wrapper by its own path and can be invoked from any cwd. File input by default generates a same-named .html; directory input by default generates in place,--title by default takes the first # level-1 heading, then falls back to the file name
• Prerequisites: Python ≥ 3.7, pandoc not required; the dependency list uses tools/md_to_html.py 's DEPENDENCIES constant as the standard; when dependencies are missing the script prints the pip install command. When Mermaid is present and --no-mermaid-ascii is not added, Node + beautiful-mermaidare also required (if missing, the wrapper prints the npm install command including the version number; version SSOT: tools/mermaid_to_ascii.mjs 's BEAUTIFUL_MERMAID_VERSION); documents without Mermaid do not need Node

Variables usable in custom templates（--template for use in the Jinja2 template passed in, not within --help 's scope): {{ content }}(body HTML),{{ toc }}(table of contents HTML),{{ styles }}(default theme CSS), {{ pygments_css }}(code highlighting CSS),{{ title }}、{{ lang }}, and the boolean switches {{ has_math }} / {{ has_mermaid }} / {{ has_toc }}(control whether to mount the corresponding CDN / sidebar)

Execution Principles

1. Run the script directly, do not invent HTML: the conversion logic, themes, and CDN mounting are all in tools/md_to_html.py; the agent should not assemble HTML on the spot or write markdown library calls on the fly—to ensure consistent output, a unified theme, and predictable extension behavior
2. Mount CDNs on demand: the script only mounts the KaTeX CDN when it detects $ ; by default Mermaid is converted to ASCII (offline), and only when conversion fails / the diagram type is unsupported (gantt / mindmap, etc.) does it fall back to mounting the Mermaid CDN; do not thoughtlessly mount the full set of CDNs for all documents (an ordinary README should not bear the network requests and loading time of formulas / diagrams)
3. Dark theme by default: by default GitHub-dark pure dark; to completely change the style use --template / --style
4. One at a time or one directory at a time: no cross-document merging; if you want to combine multiple documents into one HTML, first concatenate them into one .md
5. ASCII conversion can be turned off: when you do not want to convert to ASCII, use --no-mermaid-ascii to force the Mermaid CDN

Workflow

1. 确认输入 .md 路径（或目录）；首次使用确认依赖已装（见「输入与输出」）
2. 跑脚本：
     python3 tools/md_to_html.py <input.md> [-o <output.html>]
   批量：把 <input.md> 换成目录路径即可
3. 把生成的 .html 路径告诉用户（双击即可浏览）
4. 脚本输出含公式 / Mermaid 回退需联网的通知时，原样转达用户（通知由脚本自己检测打印，不必复述口径）
5. 上传 / 分享（可选）：产物本是本地自包含文件、不需要上传；用户要分享且 agent 已配置
   `agent-html-drop` MCP 时，调用其上传工具推 `.html` 即可——不提供其他上传方式（不经
   rsync 推 server、不写部署配置）；未配置就把本地路径交给用户

Reference examples

Example 1: a single technical document (most common)

python3 tools/md_to_html.py docs/design.md
# → 生成 docs/design.html：深色主题 + 侧边栏目录 + 代码高亮

Example 2: batch convert an entire directory

python3 tools/md_to_html.py notes/
# → notes/ 下每个 .md 就地生成同名 .html