README
¶
m2h
m2h 是一个轻量、零配置的 Markdown Web 文档浏览与 HTML 导出工具。
特性
- 直接浏览 Markdown 文件、目录或多个文档目录（打开目录时自动进入 README/index 或第一个根级文档）
- 文件树与文件名/路径筛选、全文搜索（Ctrl/Cmd+K，支持从结果直接跳转到匹配章节）、文档目录、主题和正文宽度切换
- 支持 GFM、语法高亮、数学公式、Mermaid、Vega-Lite 统计图表、脚注、Emoji 和 GitHub Alerts
- 支持 Frontmatter 标题与日期元数据、可排序表格、代码行号与长代码块折叠
- 图片、Mermaid 图表与 Vega-Lite 图表支持全屏 Lightbox 查看，可切换、通过工具栏或鼠标滚轮平滑缩放、拖动和旋转；图表以原生 SVG 渲染，放大时保持清晰；SVG 不显示底部图片信息
- 正文图片（含链接、picture、SVG）与 Mermaid、Vega-Lite 图表统一居中，WebUI 与 HTML 导出保持一致
- 正文图片延迟加载：接近视口时才请求实际资源，加载中显示内置占位图，失败折叠为统一占位并提示原始路径
- 文件修改后重新打开即可读取最新内容，刷新页面可重新扫描目录
- 输入 root 即发布边界：目录服务隐藏点开头路径，附件路由拒绝 HTML/JS/CSS 等主动 Web 内容，响应携带统一浏览器安全头
- 可将单个 Markdown 文件导出为 HTML
- 可检查 Markdown 文档的 Frontmatter、本地引用、锚点与结构问题（28 条规则与演示）
安装
Homebrew
macOS 和 Linux：
brew install lz-wang/tap/m2h
升级：
brew upgrade m2h
GitHub Releases
也可以从 GitHub Releases 下载对应平台的预编译版本。
支持：
- Linux amd64 / arm64
- macOS amd64 / arm64
- Windows amd64 / arm64
使用
浏览 Markdown
打开单个文件：
m2h README.md
打开目录：
m2h docs
同时打开多个目录或文件：
m2h docs wiki notes.md
也支持逗号分隔：
m2h docs,wiki
默认监听 127.0.0.1:8793 并自动打开浏览器。
直接向局域网提供文档服务：
m2h docs --host 0.0.0.0 --no-open
反向代理部署时建议保持 loopback 监听，仅由代理暴露公网入口：
m2h /srv/docs --host 127.0.0.1 --port 8793 --no-open
VPS 部署
通过 Nginx 等反向代理长期运行（systemd、TLS、Tinyauth 认证与健康检查）时，参见 VPS 部署指南。
常用选项：
| 选项 | 说明 |
|---|---|
--host |
监听地址 |
--port, -p |
监听端口，默认 8793 |
--open / --no-open |
是否自动打开浏览器 |
--cdn / --no-cdn |
是否从 jsDelivr CDN 按需加载 WebUI 富内容依赖，默认关闭 |
--mode |
light、dark 或 auto |
--width |
standard、wide 或 full |
--toc / --no-toc |
是否显示文档目录，默认开启（true）；只接受开关形式，不接受 =值 |
--glob |
Markdown 文件过滤规则 |
--depth, -d |
目录最大递归深度，默认 4 |
更多选项：
m2h --help
VPS 带宽受限时，可启用 CDN，让访问者的浏览器直接下载固定版本的 Mermaid/ZenUML、 KaTeX（含样式与字体）、Vega-Lite 和表格排序运行时：
m2h /srv/docs --no-open --cdn
默认或显式 --no-cdn 时使用二进制内嵌资源，可离线渲染上述内容。启用后需要访问者
能连接 cdn.jsdelivr.net，实际速度取决于其网络；WebUI 主程序与文档仍由 m2h 提供。
CDN 选项适用于整个服务，直接打开文档链接同样生效；不适用于 export 和 check。
导出 HTML
m2h export README.md
默认在 Markdown 文件旁生成同名 .html：
README.md
README.html
指定输出文件名：
m2h export README.md -o index.html
覆盖已有文件：
m2h export README.md --force
导出的 HTML 内联 Markdown 页面样式；数学公式、Mermaid、Vega-Lite 和表格排序等 增强功能按需加载网络资源。
查看全部选项：
m2h export --help
检查文档
m2h check 检查单个文件或目录的 Frontmatter、本地引用、锚点与文档结构：
m2h check README.md
m2h check docs
输出遵循 path:line:column 约定，便于终端与 IDE 定位；发现 error（或
--strict 下存在 warning）时退出码为 1。交互式终端中只为问题等级和
总结结果着色：error 为红色、warning 为黄色、全部通过为绿色；重定向、管道、
NO_COLOR 环境变量及 --format json 保持无 ANSI 颜色。文本报告以统计摘要
作为最后一行，不再重复输出 Error: check found ...：
docs/guide.md:42:17: error [local-target.missing]: target "images/topology.png" does not exist
docs/index.md:18:5: error [anchor.missing]: heading "#installation" does not exist in "guide.md"
--depth 与 --glob 和浏览命令使用同一文档范围；--format json 输出
结构化结果，--strict 把 warning 也视为失败。--enable 在默认规则之上
追加规则，--disable 移除规则且优先级更高，all 代表全部规则：
m2h check docs --depth 8 --glob '**/*.md'
m2h check docs --format json
m2h check docs --strict
m2h check docs --enable all --disable image.alt-empty
完整的 28 条规则、默认开关、触发样例、行为边界与逐字输出见
检查规则演示索引；全部命令选项见
m2h check --help。末尾检查要求恰好一个结束换行（正文\n，兼容 CRLF），
编辑器显示最后一行为空即可，无需再添加空白行。
本地目录链接（如 [算法](./algorithm/)）会打开该目录内可见的入口文档：
依次优先 README、index、00-index（.md / .markdown，名称不区分大小写），
再按路径字典序选择直属 Markdown 文件；没有直属文档时按路径深度、字典序选择可见子目录文档，不跨 root 回退。
空目录、没有可见文档的目录和目录符号链接不可作为文档入口。
本地引用使用与 WebUI 相同的路径语义：images/logo.png 相对当前文档，
/images/logo.png 相对当前输入 root（不是宿主机文件系统根目录）；多 root 模式
始终锚定引用所在的 root。//cdn.example.com/logo.png 仍是协议相对网络 URL，
与带 scheme 的外链一样不会映射到本地文件。已经识别为本地、但解析后越出
当前 root 的引用会在 WebUI 中改写到专用的 404 地址，不再把原始相对 URL
交给浏览器重新解析；m2h check 同时报告 local-target.outside-root。
Markdown 支持
m2h 支持常用 GFM Markdown，并提供以下扩展：
WebUI 富内容运行时默认从本地加载，也可通过 --cdn 切换到固定版本的 CDN，
渲染语法保持一致；HTML 导出继续按需使用 CDN。
| 类别 | 支持内容与演示 |
|---|---|
| GitHub 风格 | 语法高亮（32 种编程语言与常用配置格式）、标题锚点、脚注、Emoji、GitHub Alerts 与可排序表格 |
| 富内容 | 数学公式（$...$ / $$...$$，解析阶段保留公式原文，金额保持普通文本）、Mermaid 图表（25 种图表类型与 ZenUML）、Vega-Lite 统计图表（自包含 JSON spec） |
| 元数据 | YAML Frontmatter；标题、日期别名、描述（description）与回退规则见 Frontmatter 演示 |
| 本地引用 | 当前文档相对路径与 / 开头的当前 root 相对路径；检查行为见 本地目标演示 |
| 行内扩展 | ==高亮==、^^插入^^ 与 ++ctrl+alt+del++ 键盘按键 |
| 协作标记 | Critic Markup 行内与块级语法 |
| 图片排版 | 普通图片、链接图片、picture、SVG 与图表在正文中居中显示（WebUI 与 HTML 导出） |
| WebUI 增强 | 代码复制、行号、长代码块折叠、跨站链接新标签页打开、正文图片临近视口延迟加载，以及图片、Mermaid 与 Vega-Lite 图表 Lightbox（使用整个视口缩放与拖动，工具栏浮于图像上方，支持滚轮平滑缩放；图表以原生 SVG 放大，SVG 不显示图片信息） |
许可证
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
assets
Package assets embeds the static resources compiled into the m2h binary.
|
Package assets embeds the static resources compiled into the m2h binary. |
|
check
Package check inspects Markdown documents for integrity problems: invalid frontmatter, broken local references and document structure issues.
|
Package check inspects Markdown documents for integrity problems: invalid frontmatter, broken local references and document structure issues. |
|
cli
Package cli defines the public m2h command-line contract.
|
Package cli defines the public m2h command-line contract. |
|
export
Package export writes one Markdown file as an HTML page.
|
Package export writes one Markdown file as an HTML page. |
|
files
Package files resolves input roots and discovers safe files beneath them.
|
Package files resolves input roots and discovers safe files beneath them. |
|
markdown
Package markdown is the sole GFM parsing and HTML rendering core for m2h.
|
Package markdown is the sole GFM parsing and HTML rendering core for m2h. |
|
search
Package search ranks projected Markdown documents against a query.
|
Package search ranks projected Markdown documents against a query. |
|
server
Package server provides the browser document-server HTTP service.
|
Package server provides the browser document-server HTTP service. |
|
version
Package version validates and prints m2h build versions.
|
Package version validates and prints m2h build versions. |
|
Package webui exposes the embedded directory preview application.
|
Package webui exposes the embedded directory preview application. |