mdread

mdread

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

特性

• 左侧文件树 + 当前文档标题大纲，都可逐级折叠
• .claude/、.github/ 这类点目录里的文档照样能读
• 三套配色：日间（默认）/ 羊皮纸护眼 / 夜间
• 仿书排版：48 字/行版心、行高 1.9、中文衬线字体
• 沉浸阅读模式
• 保存 md 后浏览器自动刷新，滚动位置不丢
• Mermaid 图表与 LaTeX 公式（按需加载，不用就不下载）
• 分屏编辑：左源码右预览，滚动同步
• 保存遇到磁盘冲突会提示，可选载入磁盘版本或保留本地修改
• 编辑需要 token 授权，本机自动完成

安装

需要 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 允许 Markdown 里的原生 HTML 直通到页面（不这样的话，文档里手写的 <details>、<img> 就都失效了）。自己的笔记没问题，但别拿它对外托管来路不明的 md —— 里面的 <script> 会在访问者的浏览器里执行。

读不设防，写要 token。 路径校验能挡住越界读取（../ 与指向根外的符号链接都会被拒），点目录里也 只交出 Markdown 与图片——.env、.git/config、.ssh/id_rsa 这类文件取不到。 但它挡不住「合法地把整个目录读走」——任何能访问该端口的人都能读到你所有的文档， 阅读本身不需要任何身份验证。

写操作（编辑、保存）需要 token：启动时打印在终端，本机打开的浏览器会自动带上、 不会看到授权页；跨机器编辑时把终端里的 token 复制过去，粘贴进 /auth 页面 即可。token 走 HTTP 明文传输，不能替代 TLS。用带 token 的链接 （/auth?token=…）访问会把它留进浏览器历史，且该 token 在整个进程存活期间 一直有效——303 跳转只改了当前地址栏，抹不掉已经写进历史的那条记录。

绑到非回环地址时程序会打印以上这些警告。需要放到不受信任的网络上时，在前面 加一层带认证的反向代理（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（初版：阅读器）
• docs/superpowers/specs/2026-08-16-editing-design.md（编辑能力）

许可证

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