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 内核,三种触发方式,按手头的工具挑:
mdpub publish ...
最直接,适合脚本与终端党。其余入口都是它的包装。
编辑器里选择 公开发布 / 不公开索引发布 / 带访问码发布;三种命令都调用同一 mdpub --json 内核。
对 Claude 说「把这篇发布到服务器 / 发一个私密链接」,它会调用同一个 CLI 并回报链接。
扩展语法(服务端渲染)
渲染发生在服务端,所以任何项目的任何 .md 发到这台服务器都会渲染下面这些组件——本地不用装任何东西。它们都是合法 markdown,省略即纯 markdown。配色固定 6 色:green amber coral blue gray purple。
- frontmatter:文件最顶部
---…---,支持slug:(指定/d/<slug>地址,和--slug同等;发布不会改源文件)/title:/accent:(6 色之一)/nav: auto/toc: true|false/comments: true(划线评论;不写则保持现状)/expires: 2026-09-01(到期日,只接受日历日;false清除;不写则保持现状)/html: true(放行原始 HTML,见文末「进阶」)。 - 提示框:
:::note:::tip:::warn:::danger(或:::callout {type=warn}),框内随便写 markdown,单独一行:::收尾。 - 卡片网格:
:::grid {cols=2}里放若干:::card {accent=green title="标题"},各自:::收尾,整体再:::收尾(cols取 2 或 3)。 - 横向流程:
:::steps里放:::step {title="① 校验"}。 - 行内徽章:
:badge[文字]{color=amber},正文、列表、表格单元格里都能用。 - 嵌套:容器用相同
:::,各自:::收尾——卡片/步骤/提示框里可再放表格、代码块、徽章,甚至嵌套容器。
完整语法速查见仓库的 docs/syntax.md。写文档想要「富版式」时,直接照抄这些片段即可。
查看页能力
发布后的页面自带这些,无需配置:
| 能力 | 说明 |
|---|---|
| 自动目录 | 从标题生成侧栏 TOC,可用 frontmatter toc: false 关闭 |
| 亮/暗主题 | 右上角一键切换并记忆,跟随系统偏好 |
| 更新时间 | 正文旁显示「更新于 YYYY-MM-DD」(服务端本地时区,精确到日);输码页和源文里没有这一行 |
| 复制给 LLM | 顶栏按钮把本篇源文拷进剪贴板,可直接粘贴进对话 |
| 查看 Markdown | 顶栏链接打开 /d/{slug}/source.md,浏览器以纯文本显示源文;agent 也可直接 GET |
| 代码高亮 | 服务端 chroma 高亮,亮/暗双配色随主题切换 |
| Mermaid 图表 | ```mermaid 代码块渲染为流程图/时序图,跟随主题 |
| 本地图片 | 自动上传并按内容哈希托管,链接改写为服务器地址 |
| 访问统计 | 每次查看自增访问量,可在 list 与管理后台查看 |
| 划线评论 | 开关打开后读者可选中正文留言,作者标记已解决;默认关闭,见下面「收集反馈」 |
复制给 LLM 与 Markdown 源文
每篇已解锁的阅读页顶栏,主题按钮左边有两个控件(所有文档默认都有,不用再开开关):
- 复制给 LLM:拉取本篇源文写进剪贴板,按钮变成「已复制 ✓」。交给模型的是你当初写的 Markdown(frontmatter、
:::callout、Mermaid 源码都还在),不是渲染后的网页;划线评论不进入这份文本。 - 查看 Markdown:普通链接,打开
/d/{slug}/source.md。浏览器当纯文本显示,不会下载成附件。这个地址也可以收藏、转给别人,或丢给 agent 直接GET。
两扇门给出同一份字节。源文里发布时登记过的本地图片会改成带站点域名的绝对地址;本来就是外链的图不动。有访问码的文章走和 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 位随机量)
- slug = 文件名 + 32 个随机 hex 字符(128 位),现实中不可枚举;
- 同一个文件重发时 URL 保持稳定(binding 记录在本地
~/.config/mdpub/bindings.json); - 已经发过的公开文档想转私密,先运行
mdpub rebind --private 文件.md,再publish --private;确认新链接正常后按命令提示unpublish旧 slug。文件里如果还写着可读slug:,rebind 会拒绝——先去掉或改掉那一行。CLI 不会静默复用可猜的旧 slug,也不会在新发布成功前自动删除旧内容。
文档访问码
在「链接隐蔽性」之外再加一道口令——类似语雀的私密链接 + 访问码:拿到链接的人要输对码才能看到正文。
mdpub publish 季度复盘.md --private --code auto # 发布时设码(auto 生成 6 位随机码)
mdpub protect 季度复盘-<32位hex> --code 9573 # 或对已发布文档补设
mdpub protect 季度复盘-<32位hex> --remove-code # 清除
工作方式:
- 未解锁的访客打开链接只会看到访问码输入页,正文、摘要、分享预览(OG 描述)一概不泄露;
- 输对后种下一枚 7 天有效、仅作用于该文档的 HttpOnly cookie,期间免重复输入;改码后旧 cookie 立即失效;
- 也可以直接分享带码链接
…/d/{slug}?code=9573——打开即解锁(随后地址栏会自动洗掉码); - 服务端按 IP+文档限速:每分钟最多 5 次错误尝试,防止暴力枚举短码。
使用纪律:访问码是低强度共享凭证,不要复用任何个人密码。另外注意取舍:带码链接把「链接 + 码」合回了「知道 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。就这么多。