--- title: md-publish 使用手册 slug: usage accent: blue nav: auto toc: true --- # md-publish 使用手册 把本地的一篇 Markdown,一条命令变成一个**美观、稳定、可分享的在线链接**。 :::tip 这份手册本身就是用 md-publish 发布的——你现在看到的目录侧栏、提示框、卡片、徽章、代码高亮,全部由服务端渲染。想知道怎么写出这些效果,直接看下面的「扩展语法」一节。 ::: ## 它是什么 一个 Go 后端 + 一个瘦客户端 `mdpub` CLI,外加两个顺手的发布入口(VSCode 扩展、Claude Skill)。你写 md,它负责渲染成 HTML、托管、给你一个 `/d/{slug}` 公开链接。文中引用的本地图片会被自动扫描上传,无需手动搬运。 ## 快速开始 :::steps :::step {title="① 配置服务器与令牌"} 只需一次。把服务器地址和发布令牌写进本地配置: ```bash mdpub config --server https://md.tumbleegg.com --token <你的令牌> --default-visibility unlisted ``` 也可以改用环境变量 `MDPUB_SERVER` / `MDPUB_TOKEN`,或配置文件 `~/.config/mdpub/config.json`。 ::: :::step {title="② 发布一篇"} ```bash mdpub publish 我的笔记.md ``` 新配置默认生成含 128 位随机量的 unlisted 链接;需要公开可读文件名链接时显式加 `--public`。 ::: :::step {title="③ 打开分享"} 浏览器打开链接即可查看。阅读页正文旁有「更新于」日期,顶栏可以「复制给 LLM」或「查看 Markdown」。同一文件重复发布会携带上次 revision 做条件更新,URL 保持不变;线上已被其他客户端更新时先返回 409,不会误覆盖。 ::: ::: ## 发布命令 `mdpub publish <文件.md>` 支持这些选项: | 选项 | 作用 | 默认 | | --- | --- | --- | | `--slug ` | 自定义链接地址 `/d/`,和文件顶部 `slug:` 是同一件事 | 取 frontmatter `slug:`,再没有则取文件名 | | `--title ` | 自定义页面标题 | 正文第一个 `# 一级标题` | | `--private` | 私密发布,slug 追加不可猜的随机后缀 | 关闭 | | `--unlisted` | 与 `--private` 同为不可猜、noindex 链接 | 读配置 | | `--public` | 明确发布可索引的文件名链接 | 读配置 | | `--force` | 改绑到新 slug(不删除旧地址上的文档) | 关闭 | | `--timeout ` | 整次发布超时,如 `30s` / `5m` | `3m` | | `--code ` | 设置文档访问码(`auto` 生成 6 位随机码;空串清除;不传则保留原码) | 不传 | | `--expires ` | 到期日:`14d` / `3h` / `YYYY-MM-DD`;空串清除;不传则保留已有到期日 | 不传 | | `--json` | 机器可读输出(含 slug/title/url) | 关闭 | | `--server` / `--token` | 临时覆盖配置 | 读配置 | :::warn 新配置默认 unlisted,旧配置为兼容已有链接仍可能默认 public。可用 `mdpub config ... --default-visibility unlisted` 完成显式迁移;真正敏感内容还要加访问码。 ::: ## 固定链接:`--slug` 和 frontmatter `slug:` 想让链接跟着文件走(换目录、换机器、agent 拷到临时路径,都还更新已经发出去的那条),在文件最顶部写: ```yaml --- 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,也不碰服务器。 ## 其它命令 :::grid {cols=2} :::card {accent=green title="查看已发布"} ```bash mdpub list # 全部 mdpub list --public # 只看公开 mdpub list --unlisted # 只看未列出 mdpub list --protected # 只看设了访问码的 ``` 列出文档:slug、标题、可见性、状态、访问量、访问码、评论、更新时间、链接。`--public` 可与 `--protected` 组合,但不能和 `--unlisted` 一起用。设了访问码的文档带 🔒 并显示码本身,开了划线评论的在 COMMENTS 列显示 💬 未解决条数,到期后 STATUS 列为「已过期」(仍在清单里,可见性不变)。**看清单 ≠ 自动收回**——要改未列出或删除,用 `rebind --private` / `protect` / `unpublish`。 ::: :::card {accent=coral title="删除一篇"} ```bash mdpub unpublish ``` 从服务器移除该文档及其图片资源。 ::: :::card {accent=amber title="设置 / 清除访问码"} ```bash mdpub protect --code 9573 # 设码(--code auto 生成随机码) mdpub protect --remove-code # 清除 ``` 对已发布文档补设或撤销访问码,无需重发内容。 ::: :::card {accent=blue title="文件改名后保留链接"} ```bash mdpub move 旧路径.md 新路径.md ``` 只迁移本地 binding,不读 frontmatter、不改 slug、不碰服务器。 ::: :::card {accent=purple title="开 / 关划线评论"} ```bash mdpub comments --on # 允许读者划线留言 mdpub comments --off # 收起(评论不删除) ``` 对已发布文档就地开关,无需重发内容。见下面「收集反馈」。 ::: ::: ## 三个发布入口 同一个 `mdpub` 内核,三种触发方式,按手头的工具挑: :::grid {cols=3} :::card {accent=blue title="命令行 CLI"} `mdpub publish ...` 最直接,适合脚本与终端党。其余入口都是它的包装。 ::: :::card {accent=purple title="VSCode 扩展"} 编辑器里选择 **公开发布** / **不公开索引发布** / **带访问码发布**;三种命令都调用同一 `mdpub --json` 内核。 ::: :::card {accent=amber title="Claude Skill"} 对 Claude 说「把这篇发布到服务器 / 发一个私密链接」,它会调用同一个 CLI 并回报链接。 ::: ::: ## 扩展语法(服务端渲染) 渲染发生在服务端,所以**任何项目的任何 `.md` 发到这台服务器都会渲染下面这些组件**——本地不用装任何东西。它们都是合法 markdown,省略即纯 markdown。配色固定 6 色::badge[green]{color=green} :badge[amber]{color=amber} :badge[coral]{color=coral} :badge[blue]{color=blue} :badge[gray]{color=gray} :badge[purple]{color=purple}。 - **frontmatter**:文件最顶部 `---` … `---`,支持 `slug:`(指定 `/d/` 地址,和 `--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}`,正文、列表、表格单元格里都能用。 - **嵌套**:容器用相同 `:::`,各自 `:::` 收尾——卡片/步骤/提示框里可再放表格、代码块、徽章,甚至嵌套容器。 :::note 完整语法速查见仓库的 [`docs/syntax.md`](https://md.tumbleegg.com/d/syntax)。写文档想要「富版式」时,直接照抄这些片段即可。 ::: ## 查看页能力 发布后的页面自带这些,无需配置: | 能力 | 说明 | | --- | --- | | **自动目录** | 从标题生成侧栏 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 个)。当前阅读页永远是最新稿。若要把「周二发出去的那一版」钉住,用这一版自己的地址: ```text 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、图片和访问量。手动导出方式: ```bash mdpub export # 拉 mdpub-backup-<日期>.tar.gz 到当前目录 mdpub export -o ~/Backups/mdpub/latest.tar.gz ``` 不要直接拿生产目录试恢复。先用 `deploy/verify-backup.sh` 校验,再用 `deploy/restore-drill.sh` 解到临时目录、启动独立 server 验证三种可见性、访问码、图片与历史版本。 :::tip 生产任务使用 `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` 进单个二进制,交叉编译即可运行。 ## 私密发布 :::danger public 查看页无登录墙且文件名 slug 可枚举。新配置默认 unlisted;凡是不希望被别人撞见的内容,应明确使用 `--private`,更敏感的内容再加访问码。 ::: ```bash 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,也不会在新发布成功前自动删除旧内容。 ## 文档访问码 在「链接隐蔽性」之外再加一道口令——类似语雀的私密链接 + 访问码:拿到链接的人要输对码才能看到正文。 ```bash 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 次错误尝试,防止暴力枚举短码。 :::warn **使用纪律**:访问码是**低强度共享凭证**,不要复用任何个人密码。另外注意取舍:带码链接把「链接 + 码」合回了「知道 URL 就能看」的单因子,方便但放弃了双因子——最安全的用法是链接和码**分两个信道**发(比如链接走邮件、码走口头/即时消息)。 ::: ## 到期收回 临时分享可以设一个到期日。到期后原来的链接打开是「已过期」说明页(不是 404,也不是还能读的正文);源文和图片一并收回。过期优先于访问码:带码打开也是墓碑。 ```bash mdpub publish 工作稿.md --expires 14d # 从现在起 14 天;相对时长在发布当下换成绝对时间 mdpub publish 工作稿.md --expires 2026-09-01 # 日历日(当天 UTC 仍可读,次日过期) mdpub publish 工作稿.md --expires "" # 显式清除到期日,改成长期文档 ``` 也可以写在 frontmatter 里跟着文件走: ```yaml --- expires: 2026-09-01 # 只接受日历日;expires: false 清除 --- ``` 三态与访问码相同:**不传 `--expires`、frontmatter 也不写 `expires:`,重发会保留已有到期日**。命令行和 frontmatter 都写了且不是同一天则发布失败。frontmatter 不接受 `14d`。到期日已经在过去时发布失败,旧正文不变。把到期日改到未来或清掉再发,原链接立刻恢复。过期不改变 public / unlisted,也不删除磁盘上的版本。当前篇过期后,该篇的历史版本地址同样是墓碑。 ## 收集反馈:划线评论 给别人看的文档常常收到一句「第三段那里说反了」。划线评论把这种反馈**钉在那句原文上**:读者选中一段文字直接留言,你按着引文改,改完标记「已解决」。它不是社区评论区,更像一个长在文字上的待办清单——闭环是「标记问题 → 改文档 → 归档」。 :::steps :::step {title="① 作者:打开开关"} 默认是关的,一篇一篇开。三个入口任选: ```yaml --- comments: true # 写在 md 最顶部的 frontmatter 里,随发布生效 --- ``` ```bash mdpub comments --on # 对已发布的文档就地打开,不用重发 mdpub comments --off # 收起 ``` 或者在 `/admin` 后台点那篇文档的评论开关。 ::: :::step {title="② 读者:选中文字留言"} 在电脑上打开页面,用鼠标选中任意一段正文,旁边浮出「💬 评论」按钮,点开就能写。可以填个昵称(也可以匿名),别人能在下面回复形成一串对话。留过言的文字会显示淡黄色高亮。手机上只能看和回复,不能新建划线。 ::: :::step {title="③ 作者:改完标记已解决"} 你自己打开页面(登录过 `/admin` 就会被认出是作者)能看到每条评论旁边的「解决」按钮。改完本地 md 重新 `mdpub publish`,再点解决归档。已解决的评论不再高亮,收进折叠分组里,随时能翻回来。 ::: ::: **怎么知道有人留言了**:一期没有通知推送,靠 `mdpub list` 的 COMMENTS 列——💬 后面的数字就是这篇还没解决的评论数: ```text 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` 也显示同样的数字。 :::note **改了原文,评论会跑位吗?** 不会。每次重新发布,服务端会拿评论当时记下的原文引文去新版本里重新对位:能找到就把高亮挪过去;找不到(那句话被你删了或改得面目全非)就把它归到「⚠ 原文已修改」一组里,**保留当时的引文**,既不删除也不自动算作已解决——原文变了不等于问题被处理了。要是你后来又把那句改回来,它还会自动复位。 ::: :::warn **读者身份是君子协定,不防伪造**:评论者不需要登录,靠浏览器本地存的一枚随机 ID 认「这条是我发的」(用来给自己的评论显示删除按钮),换个浏览器就认不出了。所以划线评论适合自己人和小圈子;公开文档开评论前想清楚——任何能打开这个链接的人都能留言。评论正文一律当纯文本显示,不会解析 markdown 或 HTML。 ::: **还有几条边界**:每篇最多 500 条评论;同一个人对同一篇每分钟最多写 10 条(防刷);设了访问码的文档,没解锁就看不到也发不了评论;关掉开关后所有评论路由一律 404,已有评论只是藏起来,再打开就回来。 技术设计(锚定算法、权限矩阵、API 细节)见仓库的 [`docs/annotations.md`](https://github.com/jumpduckegg/md/blob/master/docs/annotations.md)。 ## 进阶:原始 HTML 默认所有原始 HTML 都会被转义(防 XSS)。若你信任自己的内容、需要写 `
`、`