m2h

README

m2h

m2h 是一个 Markdown 命令行工具：将文件转换为可离线打开的 HTML，在浏览器中预览文件或目录，或直接在终端阅读。

安装

Homebrew

macOS 和 Linux：

$ brew install lz-wang/tap/m2h

升级已安装的版本：

$ brew upgrade m2h

GitHub Releases

从 GitHub Releases 下载对应平台和架构的压缩包，解压后将 m2h（Windows 为 m2h.exe）加入 PATH。

m2h_<version>_linux_{amd64,arm64}.tar.gz
m2h_<version>_darwin_{amd64,arm64}.tar.gz
m2h_<version>_windows_{amd64,arm64}.zip

每个发布包均提供同名 .sha256 校验文件。

快速开始

$ m2h convert README.md
$ m2h preview docs --browser
$ m2h view README.md

使用 m2h version 或 m2h --version 查看当前版本。

转换为 HTML

# 转换单个文件，生成 README.html
$ m2h convert README.md

# 指定输出文件
$ m2h convert README.md --output public/index.html

# 转换目录中的 Markdown，并保留目录结构
$ m2h convert docs --output public/docs --depth 3 --glob '**/plan_*.md'

目录转换默认会复制非 Markdown 资源；使用 --copy-assets=false 可关闭。相对 Markdown 链接会改为对应的 .html 链接，图片和其他本地资源路径保持不变。

转换成功后，convert 会向标准输出打印转换数量、复制资源数量（如有）与每个生成 HTML 的绝对路径：

Converted 1 Markdown file.
Output HTML files:
- /work/project/README.html

选项	说明
--output, -o	单文件的目标 HTML，或目录转换的目标目录。
--glob	按相对输入目录的路径筛选 Markdown，例如 '**/guide_*.md'。仅目录可用。
--depth, -d	最大递归深度；默认 4。
--copy-assets	是否复制非 Markdown 资源；默认 true。
--mode	页面主题：light、dark 或 auto；默认 auto。
--width	正文宽度：standard（980px）、wide（1280px）或 full；默认 standard。

在浏览器中预览

# 预览单个文件；保存文件后页面会自动刷新
$ m2h preview README.md --browser

# 预览目录；提供文件树、搜索、主题和正文宽度切换
$ m2h preview docs --browser --mode dark --width wide

服务默认监听 http://127.0.0.1:8793。按 Ctrl+C 停止服务。

选项	说明
--host	监听地址；默认 127.0.0.1。
--port, -p	监听端口；默认 8793。
--browser	服务启动成功后打开系统默认浏览器。
--mode	页面主题：light、dark 或 auto；默认 auto。
--width	正文宽度：standard、wide 或 full；默认 standard。
--toc	目录预览是否显示文档目录；默认 true，关闭使用 --toc=false。
--glob	按相对输入目录的路径筛选 Markdown。仅目录可用。
--depth, -d	最大递归深度；默认 4。仅目录可用。

单文件预览会在文件变化后自动刷新。目录预览可通过界面中的刷新按钮重新扫描文件；选择始终保留在 URL 中，非默认主题、正文宽度与关闭的文档目录（?toc=false）也会保留，自动主题、标准宽度与开启的文档目录则省略，便于分享和返回。目录预览右侧的文档目录列出 H2–H4 标题，滚动时高亮当前小节，点击可跳转。

在终端中阅读

$ m2h view README.md
$ NO_COLOR=1 m2h view guide.md --mode dark

view 只接受单个 Markdown 文件，不启动 Web 服务。--mode 可选 light、dark 或 auto；auto 会尝试匹配终端背景。设置非空的 NO_COLOR 或将输出重定向时，会自动移除 ANSI 颜色。

GFM 兼容性

convert 与浏览器 preview 使用相同的渲染规则。下表中的特性均可用于生成的 HTML 和浏览器预览；view 支持基础 GFM 与 emoji，脚注和 alerts 会分别以字面文本和普通引用显示，数学公式与 Mermaid 图表不在终端渲染。

特性	简单示例
标题与锚点	## 安装；可链接到 #安装。重复标题会自动区分。
强调与删除线	**加粗**、*斜体*、~~删除~~
列表与任务列表	- 项目、1. 第一步、- [x] 已完成
引用与分割线	> 引用内容、---
链接与图片	[网站](https://example.com)、
自动链接	<https://example.com> 或 https://example.com
行内与围栏代码	`go test`；围栏以 ```go 开始、以 ``` 结束。
表格	两列的表格，例如“名称”和“值”。
脚注	说明[^1]，并在文末写 [^1]: 补充说明
emoji 短代码	:rocket: → 🚀
GitHub Alerts	> [!NOTE] 后接提示内容。
数学公式	$E = mc^2$；行间公式使用 $$...$$
Mermaid 图表	使用 ```mermaid 围栏，例如 flowchart LR 与 A --> B。
原始 HTML	直接渲染，例如 <details>内容</details>；preview 会通过安全附件路由加载标签中的相对本地资源。

数学公式和 Mermaid 图表的运行时资源已包含在输出中，生成的 HTML 可离线打开。

许可证

MIT