mdread

mdread

一个本地 Markdown 阅读器。起一个只监听本机的 HTTP 服务，用浏览器舒适地读文档。

特性

• 左侧文件树 + 当前文档标题大纲，都可逐级折叠
• 三套配色：日间（默认）/ 羊皮纸护眼 / 夜间
• 仿书排版：34 字/行版心、行高 1.9、中文衬线字体
• 沉浸阅读模式，滚动与翻页两种显示模式可切换
• 保存 md 后浏览器自动刷新，滚动位置不丢
• Mermaid 图表与 LaTeX 公式（按需加载，不用就不下载）

安装

需要 Go ≥ 1.25:

go install github.com/yanking/mdread/cmd/mdread@latest

命令会装到 $(go env GOPATH)/bin（通常是 ~/go/bin），请确认该目录在 PATH 里。

也可以从源码构建:

git clone https://github.com/yanking/mdread.git
cd mdread
make build          # 产出 ./mdread
make install        # 或安装到 GOPATH/bin

产物是单个无依赖的二进制，前端资源已经嵌在里面，没有任何构建步骤。 make dist 可交叉编译 linux / darwin / windows 的 amd64 与 arm64。

使用

mdread                  # 读当前目录
mdread ./docs           # 读指定目录
mdread README.md        # 读单个文件（以其所在目录为根）

mdread -p 8080 ./docs   # 指定端口
mdread -n ./docs        # 不自动打开浏览器

make run DOCS=~/notes 是等价的快捷方式。

对外提供服务

默认只监听 127.0.0.1。要让同网段或公网访问：

mdread --host 0.0.0.0 -p 8080 -n ~/notes
# 或
make serve DOCS=~/notes PORT=8080

启动后会列出所有可访问的地址，方便直接复制。

mdread 没有任何身份验证。 路径校验能挡住越界读取（../、符号链接、点文件都会被拒），但挡不住 「合法地把整个目录读走」——任何能访问该端口的人都能看到你所有的文档。 绑到非回环地址时程序会打印这条警告。

需要放到不受信任的网络上时，在前面加一层带认证的反向代理（nginx 的 auth_basic、Caddy 的 basicauth、或任意 OAuth 网关），并且只把 反向代理暴露出去、让 mdread 继续监听回环地址。

快捷键

开发

make check          # 格式化 + 静态检查 + 全量测试（提交前跑这个）
make test           # 只跑测试（带 -race）
make cover          # 生成覆盖率报告 coverage.html
make css            # 重新生成代码高亮的两套配色
make vendor         # 重新下载 mermaid 与 KaTeX
make help           # 看全部任务

前端是原生 HTML/CSS/JS，没有构建步骤，改完直接刷新浏览器。

设计文档

docs/superpowers/specs/2026-07-28-mdread-design.md

许可证

MIT，见 LICENSE。web/assets/vendor/ 内嵌的 Mermaid 与 KaTeX 版权归各自作者所有，均以 MIT 许可证再分发。