参与文档
改一篇文档并提交第一个 PR:仓库分工、写作与 Markdown 约定、前置元数据要求、本地构建验证,以及本站(中文文档站)的贡献口径。
开始之前,你需要
- 有一个 GitHub 账号,本机
git可用(git --version有输出)。 - 本机能跑 Hugo:
hugo version有输出。本站要求 0.147 或更高版本,标准版即可,不需要 extended。 - 会用一个文本编辑器打开文件、保存文件即可;这是本页唯一的技术门槛。
读完之后你能
- 说清「改上游英文文档」与「改本站中文译文」分别该提到哪个仓库;
- 按本站的六字段契约写出合规的前置元数据,并知道字段写在表头之后会静默失效;
- 在本地把站点跑起来,用「构建退出码 0、正文顶部出现英文原文、正文里的动作被渲染掉」三条标准验证改动;
- 避开三个会把整站构建打挂的写法,并知道被打了之后怎么定位;
- 走完 fork → 分支 → 改 → 本地验证 → 提交 → push → 开 PR 的完整链路。
这一页解决什么问题
这一页回答的是「我想给文档改点东西,从哪开始、改完怎么确认没改坏」。上游原文把规则列得很清楚,但默认你已经知道文档仓库怎么跑起来、也熟悉那套 Markdown 约定。这里补的是三件事:改哪个仓库、本地怎么看效果、以及本站自己的那套规矩。
先明确分工(原文的第一节):
- 修正与改进上游英文文档:向上游文档仓库提交议题与拉取请求。工作区里的
hugoDocs/是它的只读克隆,只用来对照原文,不要修改、更不要当作提交来源。 - 为新功能编写文档:把文档改动包含在向上游项目仓库提交的拉取请求中。
- 改进本站的中文译文与教学层:提到本站自己的仓库,口径见本站(中文文档站)的贡献口径。
写作风格
在可行的情况下遵循 Google 的开发者文档风格指南,并遵守下列约定:
- 优先使用主动语态与现在时。写「用 Hugo 构建静态站点」,而不是「使用 Hugo 可以构建静态站点」。
- 使用第二人称,而不是第三人称。写「删除文件时要小心」,而不是「用户删除文件时应小心」。
- 尽量少用副词。
- 用完整的句子引出列表与代码示例,不要用缺少主语或谓语的片段。
- 尽可能使用面向全球读者的基础英语。
- 优先写当前的最佳实践,而不是罗列多种方案或历史信息。
- 避免使用括号中的 e.g. 表达、破折号与分号。
这条约定对本站的用途:中文译文同样按上面的意图写——主动、第二人称、用完整句子引出列表。这不是为了「文风好看」,而是为了让读者一读就知道该做什么。
Markdown 约定
- 使用 ATX 标题(二至四级),不要使用 setext 标题。
- 使用折叠式链接引用;链接到同一页面内的片段时使用行内链接。
- 使用围栏代码块,不要使用缩进代码块。为代码块标注语言,模板用
go-html-template,Markdown 用md,命令行用sh,目录树用tree。 - 无序列表使用连字符,不要使用星号;有序列表的每一项都以
1.开头,而不是逐个编号。 - 用提示块(callout)强调内容,不要用加粗代替;也不要用加粗代替标题。
- 不要在 Markdown 中混入原始 HTML。
- 不要使用 Hugo 的
ref或relref短代码。 - 不要在标题之后紧接列表,先写一句引导语。
- 删除连续的空行与行尾空格。
本站的两处差异(本地化口径,上游没有对应内容):站内链接写根相对路径,且全部小写;正文从 ## 开始,一级标题由模板输出。
章节标题与文件路径
标题中不要使用反引号、加粗、斜体等格式;使用句式大小写,保持简洁;不要只设一个子标题,要么补充更多子标题,要么去掉该标题。目录名、文件名与文件路径一律用反引号包裹。
术语
术语要保持一致。例如 file name、front matter、home page 都写作两个词,website 写作一个词,Markdown 首字母大写,用 map 而不是 dictionary。同时要区分产品与可执行文件:产品与项目名用普通文本并大写,例如 Hugo;命令行可执行文件用小写并加反引号,例如 hugo。
前置元数据
文档页面使用 title、description、categories、keywords 四个必需字段,但其中只有 title 与 description 需要填写数据。可选的常用字段包括 linkTitle、weight、aliases,以及控制搜索索引的 params.searchable 等。需要引号时优先使用单引号。
以上是上游的字段契约。本站的契约是六个字段,顺序固定,缺一不可:
+++
title = "中文标题"
linkTitle = "侧栏用短名"
description = "一句话中文导语,不要照抄英文原句"
date = 2026-10-01
weight = 10
source = "https://gohugo.io/<上游相对路径,全小写>/"
+++| 字段 | 填什么 | 填错的后果 |
|---|---|---|
title |
页面标题,也是浏览器标题与 <h1> |
页面没有名字 |
linkTitle |
侧栏、上一篇/下一篇里显示的短名 | 侧栏显示过长,或回退成 title |
description |
一句话导语 | 列表页与搜索结果里没有摘要 |
date |
页面日期 | 页脚日期缺失 |
weight |
同章节内的排序,同目录内不重复 | 侧栏与上一篇/下一篇顺序错乱 |
source |
上游英文原文地址(全小写) | 正文顶部「英文原文:…」一行消失 |
实测(条件:Hugo v0.167.0,本机构建本站,单语言站点):把 source 放到 [params.teach] 之后重新构建,退出码仍然是 0,页面也照常生成,只是正文顶部那行「英文原文:…」消失(对应模板里的 .Params.source 取不到值)。构建成功不能证明前置元数据写对了,提交前请回头逐字核对这六个字段的位置。
代码示例
代码示例要短小、聚焦。模板示例用两个空格缩进,开始定界符之后、结束定界符之前各留一个空格,并始终以函数的规范形式调用函数或方法。用 file 与 copy 属性可以显示文件名并添加复制按钮。
转义与短代码
这一节是本站与上游差异最大、也最容易翻车的地方,本地化增补。
本站内容里只允许两个短代码的正式调用:note 和 quick-reference。上游的 code-toggle、new-in、deprecated-in、include、glossary-term 等在本站没有对应模板;照抄上游调用会让 Hugo 报
failed to extract shortcode: template for shortcode "…" not found并且整个站点构建失败——不是单页失败。上游的这几类写法改成纯 Markdown:配置与前例改成围栏代码块(语言标 toml / yaml / json),版本提示写成行内文字「(0.159.2 新增)」,include 的内容翻译后内联到该处。
还有一条更隐蔽的规则:要展示短代码语法本身,必须写成转义形式。Hugo 在 Markdown 解析之前就会扫描并提取短代码,围栏代码块与行内代码都不豁免。你写的内容与页面显示的关系是:
| 你在文件里写 | 页面上显示成什么 | 什么时候用 |
|---|---|---|
{{< name >}} |
一对花括号包住尖括号形式的 name 调用 |
展示标准记法 |
{{% name %}} |
一对花括号包住百分号形式的 name 调用 |
展示 Markdown 记法 |
{{</* name */>}} |
上面第一行那种转义写法本身(多一层星号) | 要讲解转义规则时 |
注意三点:
- 上表「你在文件里写」一列里的
/*与*/一个都不能省:转义判定靠的就是这对注释记号({{<…>}}),与反斜杠无关。只写一半不算转义,那一行会被当成真的调用,构建随即失败。 - 本页的「页面上显示成什么」一列用文字描述,而不是把渲染结果写成代码。原因是本站做不到:主题的 Markdown 渲染会对代码内容再做一次转义,写在代码里的花括号转义实体不会还原成花括号,读者会看到实体本身。这是本站已知的显示限制,不是你的写法有问题——你自己写文档时照抄「你在文件里写」那一列即可。
- 围栏代码块不豁免这条规则,行内代码同样不豁免:写成 ``
{{< name >}}是安全的,但把转义记号省掉的裸定界符,即使包在行内代码或 ```text 围栏里,也一样会被提取。凡是展示短代码调用,一律加上/*与*/。(写这一节时就实测过一次:一个省掉注释记号的裸调用让整站构建失败,报unrecognized character in shortcode action。)
你应当看到什么:构建一次,页面源码里出现的应该是渲染后的普通文本;如果你在产物里还能搜到裸的定界符,说明这几行被当成真的调用了,构建会随即报错。
第二条禁用项是 Hugo 的短代码占位符前缀字面串。内容里一旦出现这个完整字符串,Hugo 会报
illegal state in content; shortcode token missing end delim并且错误归因到正在渲染的那个页面上——看起来像那一页有问题,实际是字符串与占位符机制冲突。需要展示时,在中间插入零宽字符打断它;注意实体要写在代码 span 之外,写在反引号里不会被解码,读者会看到实体本身。
本地预览与 GitHub 工作流
先把文档站点跑起来
在改之前先确认「改之前就是好的」。在仓库根目录执行(站点源码就在这一层:hugo.toml、content/、themes/):
hugo --ignoreCache --renderToMemory --quiet
echo $? # Windows PowerShell 用 $LASTEXITCODE你应当看到什么:退出码 0,终端没有任何输出(--quiet 会压掉常规信息,但报错与警告仍会显示)。这一步很关键:
想在浏览器里看效果,用 hugo server,然后打开终端提示的地址(默认 http://localhost:1313/)。页脚显示的「最后更新」来自 Git 提交时间(本站开启了 enableGitInfo),所以刚提交过的页面日期会变成这次提交的时间——这是预期行为,不是你改坏了。
完整流程
-
派生上游文档仓库(改本站译文时,派生的是本站自己的仓库)。
-
克隆你的派生仓库。
-
新建分支,分支名要有描述性并包含对应的议题编号(如果有):
bashgit checkout -b restructure-foo-page-99999你应当看到什么:
git branch --show-current打印出刚建的分支名。到提交前再确认一次自己没在默认分支上改。 -
修改文档。
-
在本地构建站点,预览你的改动(命令见上一节)。
-
提交改动。沿用在开发流程中说明的提交信息约定,但摘要以
content、theme、config、all或misc之一开头,后接冒号、空格,以及以大写字母开头的简短说明;可选地添加引用议题的Fixes、Closes行。例如:bashgit commit -m "content: Restructure the taxonomy page This restructures the taxonomy page by splitting topics into logical sections, each with one or more examples. Fixes #9999 Closes #9998" -
把新分支推送到你的派生仓库。
-
访问文档仓库,创建拉取请求(PR)。
-
项目维护者会审查你的 PR,可能会要求修改。维护者合并 PR 之后,你可以删除该分支。
提交前跑这三条命令
在仓库根目录执行,三条都通过再开 PR:
| 命令 | 通过的样子 | 它能查出什么 |
|---|---|---|
hugo --ignoreCache --renderToMemory --quiet |
退出码 0 | 短代码、前置元数据、模板语法类问题 |
pwsh -NoProfile -File .translation/audit-links-case.ps1 |
末行「全部站内链接大小写与存在性均正确 ✓」(需先构建出 public/) |
站内链接写成了驼峰,或指向了不存在的页面 |
pwsh -NoProfile -File .translation/audit-teach.ps1 |
输出按章节统计的表;新增页面应出现在教学块计数里 | 教学层缺字段 |
提交前逐条对一遍(与参与贡献首页的自查清单同源):
- 六个前置字段齐全,且都在所有表头之前;
- 正文从
##开始,站内链接根相对且全小写; - 上游的技术细节没有被删:命令、参数、默认值、表格、代码块、外链都在;
- 页面能构建,并且在
public/里能找到对应的产物文件。
本站(中文文档站)的贡献口径
这一段是本地化增补,写的是本站自己的规矩。本站是什么、仓库在哪、规模多大,见参与贡献首页的同一节。
本站欢迎什么样的文档改动
- 译文修正:错译、漏译、术语不一致、中文语病。译文以对上游英文原文的翻译为准。
- 教学层增补:补「这一页解决什么问题」、关键步骤后的「你应当看到什么」、按「症状 → 真因 → 怎么修」组织的常见坑表。这是本站与上游直译最大的区别,也是最欢迎的一类改动。
- 格式与一致性:站内链接、术语、前置元数据是否笔误。
- 不欢迎的改动:为了让文字「更好看」而删掉上游的命令、参数、默认值、表格、代码块或外链;以及把没有实测依据的结论写成事实。
与上游的三点不同
- 不能照抄上游的短代码调用,本站只有
note与quick-reference;照抄会让整站构建失败。改写方法与转义写法见转义与短代码。 - 前置元数据是本站的六字段契约,字段必须写在表头之前,见前置元数据。
- 验收靠脚本,不靠肉眼:
.translation/accept.ps1会依次跑覆盖率、权重归一、严格构建、站内链接检查与铁律扫描,构建那一步会打印build exit=0。
一条特殊要求:区分「上游写的」与「本站实测的」
上游没写、由本站实测得出的结论,必须标「实测」,并写清测量条件(Hugo 版本、单语言还是多语言站点、操作系统等)。例如本页那条「把 source 写到表头之后,构建仍然退出码 0、只是正文顶部那行原文链接消失」,就注明了 Hugo 版本与本机条件。
为什么不许臆造:读者是照着结论做事的。一条没有条件的「实测」结论,换一个 Hugo 版本就可能不成立;而没有标注的推断,会被读者当成官方文档。
常见坑
| 症状 | 真因 | 怎么修 |
|---|---|---|
| 改了文件,本地预览没变化 | 改的不是当前渲染的那一份(例如改了 hugoDocs/ 只读克隆),或服务器没重启到该目录 |
确认路径在 content/ 下;hugo server 是从仓库根目录启动的 |
构建报 failed to extract shortcode: template for shortcode "…" not found |
正文里有未转义的短代码定界符,或照抄了上游的短代码调用 | 改成纯 Markdown 或转义写法,见转义与短代码 |
构建报 illegal state in content; shortcode token missing end delim,且指向的页面看不出问题 |
正文里出现了 Hugo 的短代码占位符前缀字面串 | 用零宽字符打断该字面串;报错归因到别的页面是已知现象 |
| 页面正常,但正文顶部少了「英文原文:…」 | source 被写到了 [params.teach] 等表头之后 |
把六个标量字段整体上移到所有表头之前 |
| 站点某些链接线上 404,本地看着正常 | 站内链接写成了驼峰(Hugo 输出 URL 全小写) | 跑 .translation/audit-links-case.ps1,按「应为」一列改 |
在子目录里跑 hugo 也返回 0,就以为通过了 |
子目录不是站点根,构建出的站点规模与本站完全不符(实测 Pages │ 4) |
一律在仓库根目录执行,见先把文档站点跑起来;用输出的 Pages 数量与本站规模对一下(本站 1966 页) |
无 Git 环境下构建报 fatal: not a git repository |
本站开启了 Git 信息联动,缺 .git 会整站失败 |
加 --config hugo.toml,hugo.nogit.toml |
| 提交信息被维护者要求重写 | 摘要没有用 content / theme / config / all / misc 开头,或没写祈使句 |
按完整流程第 6 步的格式改;用 git commit --amend 修正 |