md-publish 使用手册

更新于 2026-10-21

md-publish 使用手册

把本地的一篇 Markdown,一条命令变成一个美观、稳定、可分享的在线链接。

这份手册本身就是用 md-publish 发布的——你现在看到的目录侧栏、提示框、卡片、徽章、代码高亮,全部由服务端渲染。想知道怎么写出这些效果,直接看下面的「扩展语法」一节。

它是什么

一个 Go 后端 + 一个瘦客户端 mdpub CLI,外加两个顺手的发布入口(VSCode 扩展、Claude Skill)。你写 md,它负责渲染成 HTML、托管、给你一个 /d/{slug} 公开链接。文中引用的本地图片会被自动扫描上传,无需手动搬运。

快速开始

① 配置服务器与令牌

只需一次。把服务器地址和发布令牌写进本地配置:

mdpub config --server https://md.tumbleegg.com --token <你的令牌> --default-visibility unlisted

也可以改用环境变量 MDPUB_SERVER / MDPUB_TOKEN,或配置文件 ~/.config/mdpub/config.json。

② 发布一篇
mdpub publish 我的笔记.md

新配置默认生成含 128 位随机量的 unlisted 链接;需要公开可读文件名链接时显式加 --public。

③ 打开分享

浏览器打开链接即可查看。阅读页正文旁有「更新于」日期,顶栏可以「复制给 LLM」或「查看 Markdown」。同一文件重复发布会携带上次 revision 做条件更新,URL 保持不变;线上已被其他客户端更新时先返回 409,不会误覆盖。

发布命令

mdpub publish <文件.md> 支持这些选项:

选项 作用 默认
--slug <s> 自定义链接地址 /d/<s>,和文件顶部 slug: 是同一件事 取 frontmatter slug:,再没有则取文件名
--title <t> 自定义页面标题 正文第一个 # 一级标题
--private 私密发布,slug 追加不可猜的随机后缀 关闭
--unlisted 与 --private 同为不可猜、noindex 链接 读配置
--public 明确发布可索引的文件名链接 读配置
--force 改绑到新 slug(不删除旧地址上的文档) 关闭
--timeout <d> 整次发布超时,如 30s / 5m 3m
--code <c> 设置文档访问码(auto 生成 6 位随机码;空串清除;不传则保留原码) 不传
--expires <e> 到期日:14d / 3h / YYYY-MM-DD;空串清除;不传则保留已有到期日 不传
--json 机器可读输出(含 slug/title/url) 关闭
--server / --token 临时覆盖配置 读配置

新配置默认 unlisted,旧配置为兼容已有链接仍可能默认 public。可用 mdpub config ... --default-visibility unlisted 完成显式迁移;真正敏感内容还要加访问码。

固定链接:--slug 和 frontmatter slug:

想让链接跟着文件走(换目录、换机器、agent 拷到临时路径,都还更新已经发出去的那条),在文件最顶部写:

---
slug: bank4-lite
---

这和 mdpub publish 文件.md --slug bank4-lite 是同一件事的两个入口,都会发到 /d/bank4-lite。两个都写了、规范化之后却不是同一个地址,发布失败,不会悄悄挑一个。发布过程不会改你的源文件:slug: 是你写进去的身份,不是工具替你盖的章。

已经绑定在地址 A、文件里却改成了 B 时,没有 --force 会失败,避免不知情搬家;加上 --force 才发到 B,并且不会自动删除 A 上的旧文档。确认新链接没问题后,自己再 mdpub unpublish A。

已经写了可读 slug: 的文件不能 mdpub rebind --private:先去掉或改掉这一行,否则下次一发又会按文件里的地址抢回去。mdpub move 只搬家本机绑定,不读 frontmatter 去改 slug,也不碰服务器。

其它命令

查看已发布
mdpub list                 # 全部
mdpub list --public        # 只看公开
mdpub list --unlisted      # 只看未列出
mdpub list --protected     # 只看设了访问码的

列出文档:slug、标题、可见性、状态、访问量、访问码、评论、更新时间、链接。--public 可与 --protected 组合,但不能和 --unlisted 一起用。设了访问码的文档带 🔒 并显示码本身,开了划线评论的在 COMMENTS 列显示 💬 未解决条数,到期后 STATUS 列为「已过期」(仍在清单里,可见性不变)。看清单 ≠ 自动收回——要改未列出或删除,用 rebind --private / protect / unpublish。

删除一篇
mdpub unpublish <slug>

从服务器移除该文档及其图片资源。

设置 / 清除访问码
mdpub protect <slug> --code 9573   # 设码(--code auto 生成随机码)
mdpub protect <slug> --remove-code # 清除

对已发布文档补设或撤销访问码,无需重发内容。

文件改名后保留链接
mdpub move 旧路径.md 新路径.md

只迁移本地 binding,不读 frontmatter、不改 slug、不碰服务器。

开 / 关划线评论
mdpub comments <slug> --on   # 允许读者划线留言
mdpub comments <slug> --off  # 收起(评论不删除)

对已发布文档就地开关,无需重发内容。见下面「收集反馈」。

三个发布入口

同一个 mdpub 内核,三种触发方式,按手头的工具挑:

命令行 CLI

mdpub publish ... 最直接,适合脚本与终端党。其余入口都是它的包装。

VSCode 扩展

编辑器里选择 公开发布 / 不公开索引发布 / 带访问码发布;三种命令都调用同一 mdpub --json 内核。

Claude Skill

对 Claude 说「把这篇发布到服务器 / 发一个私密链接」,它会调用同一个 CLI 并回报链接。

扩展语法(服务端渲染)

渲染发生在服务端,所以任何项目的任何 .md 发到这台服务器都会渲染下面这些组件——本地不用装任何东西。它们都是合法 markdown,省略即纯 markdown。配色固定 6 色:green amber coral blue gray purple。

完整语法速查见仓库的 docs/syntax.md。写文档想要「富版式」时,直接照抄这些片段即可。

查看页能力

发布后的页面自带这些,无需配置:

能力 说明
自动目录 从标题生成侧栏 TOC,可用 frontmatter toc: false 关闭
亮/暗主题 右上角一键切换并记忆,跟随系统偏好
更新时间 正文旁显示「更新于 YYYY-MM-DD」(服务端本地时区,精确到日);输码页和源文里没有这一行
复制给 LLM 顶栏按钮把本篇源文拷进剪贴板,可直接粘贴进对话
查看 Markdown 顶栏链接打开 /d/{slug}/source.md,浏览器以纯文本显示源文;agent 也可直接 GET
代码高亮 服务端 chroma 高亮,亮/暗双配色随主题切换
Mermaid 图表 ```mermaid 代码块渲染为流程图/时序图,跟随主题
本地图片 自动上传并按内容哈希托管,链接改写为服务器地址
访问统计 每次查看自增访问量,可在 list 与管理后台查看
划线评论 开关打开后读者可选中正文留言,作者标记已解决;默认关闭,见下面「收集反馈」

复制给 LLM 与 Markdown 源文

每篇已解锁的阅读页顶栏,主题按钮左边有两个控件(所有文档默认都有,不用再开开关):

两扇门给出同一份字节。源文里发布时登记过的本地图片会改成带站点域名的绝对地址;本来就是外链的图不动。有访问码的文章走和 HTML 阅读页同一道门:未解锁只看到输码页,已解锁的 cookie 对源文自动生效。带码打开 …/source.md?code=正确码 会跳到不带码的源文地址。

输码页上没有这两个按钮。点「复制给 LLM」不算多一次访问;在浏览器里打开源文地址,或 agent 直接拉取,才计一次阅读。

钉住某一版

每次成功发布都会留下一个完整版本(正文 + 图,最近约 10 个)。当前阅读页永远是最新稿。若要把「周二发出去的那一版」钉住,用这一版自己的地址:

https://md.tumbleegg.com/d/{slug}/r/{revision}
https://md.tumbleegg.com/d/{slug}/r/{revision}/source.md

revision 在这次 mdpub publish --json 的返回里,也在 mdpub list 背后的数据里。后台每一篇有「复制此版本链接」,复制的就是当前这一版的钉住地址。

历史页会标明「历史版本」,显示那一版的「更新于」日期,并提供回当前页的链接。历史页不开划线评论。访问码和解锁凭证与当前页同一道门。当前这篇已经过期时,历史地址同样是墓碑——收回是整篇的决定,不能靠旧链接继续读。

未知的、或已经不在保留窗口里的 revision,和「没有这篇」一样是找不到。

管理后台

浏览器打开 /admin,用服务器的发布令牌登录(HttpOnly cookie 记住登录)。页头能看到总篇数、公开 N、总访问量、未解决评论数。默认列出全部文档;可用「全部 / 公开 / 未列出 / 需访问码」就地筛选(不重新登录)。公开文档的标记比未列出更扎眼——未列出是安静的默认,公开才是需要过目的状态。

每一篇能点进阅读页、复制访问码或带码链接、就地设/改/清码、开关划线评论、删除,以及 复制此版本链接(钉住当前 revision 的历史地址)。带访问码的文档标 🔒,码默认打点隐藏、点击显示。到期后文档仍留在列表里,额外标「已过期」,公开 / 未列出标记不变;改一个未来到期日或清掉到期日再发布,过期标记会消失。

未登录只看到登录页,不会泄露公开篇数或任何文档信息。

备份导出

服务器的数据包含当前内容、完整历史 revision、图片和访问量。手动导出方式:

mdpub export                              # 拉 mdpub-backup-<日期>.tar.gz 到当前目录
mdpub export -o ~/Backups/mdpub/latest.tar.gz

不要直接拿生产目录试恢复。先用 deploy/verify-backup.sh 校验,再用 deploy/restore-drill.sh 解到临时目录、启动独立 server 验证三种可见性、访问码、图片与历史版本。

生产任务使用 deploy/backup.sh:同一份归档校验后分别落 primary 与不同设备/远端挂载的 secondary,并比较 SHA-256。完整配置和季度恢复演练见 docs/production-readiness.md。

服务端配置

自建服务时,服务端读这些环境变量:

变量 默认 说明
MDPUB_TOKEN (必填) 发布 API 令牌,设成一段长随机串
MDPUB_ADDR :8080 监听地址
MDPUB_DATA ./data 数据目录(markdown + 图片 + 访问量)
MDPUB_BASE_URL http://localhost:8080 拼接返回链接用的公开地址

部署方式:Docker + GHCR + Nginx,推送到 master 由 GitHub Actions 自动构建镜像并 SSH 上线。模板/CSS/JS 全部 embed 进单个二进制,交叉编译即可运行。

私密发布

public 查看页无登录墙且文件名 slug 可枚举。新配置默认 unlisted;凡是不希望被别人撞见的内容,应明确使用 --private,更敏感的内容再加访问码。

mdpub publish 季度复盘.md --private
# → https://md.tumbleegg.com/d/季度复盘-8f3a2c4d9e...32位hex   (128 位随机量)

文档访问码

在「链接隐蔽性」之外再加一道口令——类似语雀的私密链接 + 访问码:拿到链接的人要输对码才能看到正文。

mdpub publish 季度复盘.md --private --code auto   # 发布时设码(auto 生成 6 位随机码)
mdpub protect 季度复盘-<32位hex> --code 9573          # 或对已发布文档补设
mdpub protect 季度复盘-<32位hex> --remove-code        # 清除

工作方式:

使用纪律:访问码是低强度共享凭证,不要复用任何个人密码。另外注意取舍:带码链接把「链接 + 码」合回了「知道 URL 就能看」的单因子,方便但放弃了双因子——最安全的用法是链接和码分两个信道发(比如链接走邮件、码走口头/即时消息)。

到期收回

临时分享可以设一个到期日。到期后原来的链接打开是「已过期」说明页(不是 404,也不是还能读的正文);源文和图片一并收回。过期优先于访问码:带码打开也是墓碑。

mdpub publish 工作稿.md --expires 14d          # 从现在起 14 天;相对时长在发布当下换成绝对时间
mdpub publish 工作稿.md --expires 2026-09-01   # 日历日(当天 UTC 仍可读,次日过期)
mdpub publish 工作稿.md --expires ""           # 显式清除到期日,改成长期文档

也可以写在 frontmatter 里跟着文件走:

---
expires: 2026-09-01   # 只接受日历日;expires: false 清除
---

三态与访问码相同:不传 --expires、frontmatter 也不写 expires:,重发会保留已有到期日。命令行和 frontmatter 都写了且不是同一天则发布失败。frontmatter 不接受 14d。到期日已经在过去时发布失败,旧正文不变。把到期日改到未来或清掉再发,原链接立刻恢复。过期不改变 public / unlisted,也不删除磁盘上的版本。当前篇过期后,该篇的历史版本地址同样是墓碑。

收集反馈:划线评论

给别人看的文档常常收到一句「第三段那里说反了」。划线评论把这种反馈钉在那句原文上:读者选中一段文字直接留言,你按着引文改,改完标记「已解决」。它不是社区评论区,更像一个长在文字上的待办清单——闭环是「标记问题 → 改文档 → 归档」。

① 作者:打开开关

默认是关的,一篇一篇开。三个入口任选:

---
comments: true    # 写在 md 最顶部的 frontmatter 里,随发布生效
---
mdpub comments <slug> --on    # 对已发布的文档就地打开,不用重发
mdpub comments <slug> --off   # 收起

或者在 /admin 后台点那篇文档的评论开关。

② 读者:选中文字留言

在电脑上打开页面,用鼠标选中任意一段正文,旁边浮出「💬 评论」按钮,点开就能写。可以填个昵称(也可以匿名),别人能在下面回复形成一串对话。留过言的文字会显示淡黄色高亮。手机上只能看和回复,不能新建划线。

③ 作者:改完标记已解决

你自己打开页面(登录过 /admin 就会被认出是作者)能看到每条评论旁边的「解决」按钮。改完本地 md 重新 mdpub publish,再点解决归档。已解决的评论不再高亮,收进折叠分组里,随时能翻回来。

怎么知道有人留言了:一期没有通知推送,靠 mdpub list 的 COMMENTS 列——💬 后面的数字就是这篇还没解决的评论数:

SLUG           TITLE  VISIBILITY  STATUS  VIEWS  CODE  COMMENTS  UPDATED           URL
demo-plain     普通文档   public      -       0      -     on        2026-07-27 22:23  http://localhost:8099/d/demo-plain
demo-comments  演示文档   public      -       0      -     💬 2      2026-07-27 22:23  http://localhost:8099/d/demo-comments

- = 没开评论,on = 开着但没有待处理,💬 2 = 有 2 条等你处理。后台 /admin 也显示同样的数字。

改了原文,评论会跑位吗? 不会。每次重新发布,服务端会拿评论当时记下的原文引文去新版本里重新对位:能找到就把高亮挪过去;找不到(那句话被你删了或改得面目全非)就把它归到「⚠ 原文已修改」一组里,保留当时的引文,既不删除也不自动算作已解决——原文变了不等于问题被处理了。要是你后来又把那句改回来,它还会自动复位。

读者身份是君子协定,不防伪造:评论者不需要登录,靠浏览器本地存的一枚随机 ID 认「这条是我发的」(用来给自己的评论显示删除按钮),换个浏览器就认不出了。所以划线评论适合自己人和小圈子;公开文档开评论前想清楚——任何能打开这个链接的人都能留言。评论正文一律当纯文本显示,不会解析 markdown 或 HTML。

还有几条边界:每篇最多 500 条评论;同一个人对同一篇每分钟最多写 10 条(防刷);设了访问码的文档,没解锁就看不到也发不了评论;关掉开关后所有评论路由一律 404,已有评论只是藏起来,再打开就回来。

技术设计(锚定算法、权限矩阵、API 细节)见仓库的 docs/annotations.md。

进阶:原始 HTML

默认所有原始 HTML 都会被转义(防 XSS)。若你信任自己的内容、需要写 <details>、<video>、<iframe> 等原生标签,在 frontmatter 里声明:

---
html: true
---

默认关闭,逐文档显式开启。开启后 <details> 等 HTML 可展示,但 nonce CSP 会阻止正文里的 <script>、onclick= 与外部脚本执行;需要任意 JavaScript 时必须使用独立 origin。


一句话上手:mdpub config 配一次,之后 mdpub publish 文件.md 拿链接,私密内容加 --private。就这么多。