非程序员怎样把 Markdown 稿交给 GitHub Pages 静态博客编辑
用原创 Markdown 稿、实际统一差异、只读本地预览和交接清单,说明作者、审稿者与维护者怎样分工;GitHub Pages 与 PR 只按官方文档说明。
朋友愿意为你的静态博客写一段发布说明,却不熟悉 Git、分支和站点构建。可以先用三份文件完成一轮合作:原始 Markdown、审读后的 Markdown,以及两者之间的差异。
本文把这条本地交接走一遍。示例材料全部是原创、非敏感文本;差异和预览都在本机生成。文中提到 GitHub Pages、网页编辑、PR 或发布源的地方,只说明GitHub Docs 怎样描述这些能力,不表示本文已验证 GitHub 网页编辑、账号权限、PR、合并或 Pages 部署。
可先下载完整本地交接包,也可打开英文只读差异页。压缩包中有起始稿、审读稿、统一差异、交接清单和同一份只读页面。
先把交接对象缩成一个 Markdown 文件
这次的样本是静态博客里的一则发布说明。作者只需要修改正文,不需要知道模板、导航或部署设置。维护者先给出三个约定:目标文件名、可以改的段落,以及一条能让人确认版本的短语。
draft-v1.md 的起始文本如下:
# A release note that needs one more condition
The maintenance guide says that a release check should happen before publishing.
## Draft instruction
Run the validation command before publishing.
Revision: draft-v1
作者的交付不是“我改好了”这句话,而是这个完整文件。完整文件保留标题、段落和版本标记,审稿者才知道要把哪一版拿来比较。若现有站点有 front matter、文件名规则或图片目录,维护者应把这些写进自己的模板;不要让作者猜。
审稿者怎样把一句模糊指令改成可交接的内容
审稿者收到草稿后,先检查它是否仍然只改约定的范围,再把需要的条件写回 Markdown。这个样本把“运行验证”补成了谁在什么位置做什么、留下什么记录:
## Reviewed instruction
From the project root, run the validation command documented for this site. Record the result or the failing step in the handoff note, then give the editor this revised Markdown instead of changing a copied webpage.
Revision: reviewed-v2
这里的 validation command 由维护者替换成本站实际命令。例如 Trylog 使用 pnpm release:check,它会同步本地内容、检查译文与资源、构建页面,再核对 HTML、RSS 和 sitemap。其他生成器应使用自己项目中已定义的检查命令。
审稿结果写进 reviewed-v2.md,并保留 draft-v1.md。在下载包目录运行下面这条命令,可以重新生成本文使用的统一差异。diff 发现差异时返回 1,这是正常结果;大于 1 才表示读取或执行错误。
diff -u --label draft-v1.md --label reviewed-v2.md draft-v1.md reviewed-v2.md > draft-to-reviewed.diff
--- draft-v1.md
+++ reviewed-v2.md
@@ -2,8 +2,8 @@
The maintenance guide says that a release check should happen before publishing.
-## Draft instruction
+## Reviewed instruction
-Run the validation command before publishing.
+From the project root, run the validation command documented for this site. Record the result or the failing step in the handoff note, then give the editor this revised Markdown instead of changing a copied webpage.
-Revision: draft-v1
+Revision: reviewed-v2
这个 diff 让审稿从“读一遍整篇文章”变成两个可回答的问题:是否只改了允许的段落?新增的条件是否清楚且不超出已知事实?如果答案不是肯定的,退回的对象仍是 Markdown 文件,不是已经发布的网页。

英文只读预览把两份稿件和对应差异放在一起。
三个角色各自交出什么
| 角色 | 本轮交付 | 交给下一位的人需要核对什么 |
|---|---|---|
| 作者 | draft-v1.md,以及可编辑范围说明 | 文件完整、没有混入密码或私人材料、版本标记仍在 |
| 审稿者 | reviewed-v2.md、draft-to-reviewed.diff、交接意见 | 每个新增或删除都能在差异中看到;条件和事实回到相应句子附近 |
| 站点维护者 | 本地渲染结果、站点自己的检查记录、是否接纳的决定 | Markdown 在实际生成器中是否正常;接纳范围是否符合站点规则 |
分工的关键是让每个人交出可复核的中间产物。作者不需要取得发布权限;审稿者也不应替维护者改变部署设置。维护者可以在接到完整材料后决定是否把内容放入现有站点的受控流程。
本地预览回答的是排版问题,差异回答的是改动问题
我把两份 Markdown 和统一差异渲染成一个只读 HTML 页面,再在本地站点里打开它。这样能同时看到标题层级、段落、长句折行和差异是否对应。下载包里的 local-review-demo.html 可以离线打开;页面没有登录、上传、保存或发布按钮。
本地预览通过后,维护者仍需运行自己站点规定的检查。这一步的输入是接纳后的 Markdown,输出是该站点的本地构建或检查记录。若生成器报错、图片路径失效或链接不符合规则,应把错误写进交接意见,回到 Markdown 修订;不要直接在成品 HTML 里补字,因为下一次构建会覆盖它。
这是一条恢复边界:本地预览可以证明本地页面在当前环境里呈现出来,不能证明远端仓库已经收到文件,更不能证明外部托管已部署。把这两个结果分开,出错时就知道要回到稿件、站点检查,还是另行处理远端流程。
GitHub Docs 能说明什么,不能替本地演示说明什么
如果现有站点确实使用 GitHub Pages,GitHub Pages 官方说明把它描述为:从 GitHub 仓库取得 HTML、CSS 和 JavaScript,可选经过构建,再发布为网站的静态托管服务。它解释了为什么文章源文件、构建产物与公开网页是不同阶段。
官方文件编辑说明描述了网页编辑已有文件、填写提交信息、把修改放到新分支并创建 PR 的路线;它也说明,编辑其他人的仓库时可能会走 fork 与 PR。那是平台文档描述的路径。实际账户能否编辑、受保护分支如何要求审阅、以及哪些目录能写,仍由具体仓库的权限和规则决定,需要在被授权的环境中单独核对。
官方审阅说明把评论、批准和要求修改列为审阅动作,并说明 PR 作者不能批准自己的 PR。它有助于维护者设计“作者交稿、他人审稿”的责任边界。
发布源说明区分从分支发布与用 GitHub Actions 工作流发布,并写明配置发布源需要仓库的 admin 或 maintainer 权限。选择发布源属于站点维护工作,交稿不需要连带改变它。
一张可以直接跟着走的交接清单
下载包中的 handoff-checklist.md 把下列项目写成可勾选条目:
- 作者复制站点给出的模板,只在约定的 Markdown 区域写作,并保留版本标记。
- 审稿者保留原稿,生成
reviewed-v2.md和统一 diff;遇到不清楚的事实时,在稿件旁边提出问题,不补写成结论。 - 维护者在本地渲染审读稿,检查标题、段落、链接、图片和站点自己的内容规则。
- 若站点接纳稿件,维护者才按该站点已授权的版本控制与发布流程继续;若不接纳,保留稿件与原因,作者仍能从上一步继续修改。
这条路线并不把静态博客变成访客自助发文系统。需要账户、私人草稿、跨设备保存或即时发布时,还要设计身份、权限、持久化存储和审核机制。对于一篇由编辑接手的 Markdown 稿件,先把稿件、差异、预览和决定交清楚,已经能让非程序员作者参与,又不会把站点维护责任悄悄转给他们。