参与贡献

参与文档

改一篇文档并提交第一个 PR:仓库分工、写作与 Markdown 约定、前置元数据要求、本地构建验证,以及本站(中文文档站)的贡献口径。

难度
入门
预计用时
首次约 40–60 分钟(含克隆与首次构建)

开始之前,你需要

  • 有一个 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 等。需要引号时优先使用单引号。

以上是上游的字段契约。本站的契约是六个字段,顺序固定,缺一不可:

toml
+++
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 */>}} 上面第一行那种转义写法本身(多一层星号) 要讲解转义规则时

注意三点:

  1. 上表「你在文件里写」一列里的 /* 与 */ 一个都不能省:转义判定靠的就是这对注释记号({{< … >}}),与反斜杠无关。只写一半不算转义,那一行会被当成真的调用,构建随即失败。
  2. 本页的「页面上显示成什么」一列用文字描述,而不是把渲染结果写成代码。原因是本站做不到:主题的 Markdown 渲染会对代码内容再做一次转义,写在代码里的花括号转义实体不会还原成花括号,读者会看到实体本身。这是本站已知的显示限制,不是你的写法有问题——你自己写文档时照抄「你在文件里写」那一列即可。
  3. 围栏代码块不豁免这条规则,行内代码同样不豁免:写成 `` {{< name >}} 是安全的,但把转义记号省掉的裸定界符,即使包在行内代码或 ```text 围栏里,也一样会被提取。凡是展示短代码调用,一律加上 /* 与 */。(写这一节时就实测过一次:一个省掉注释记号的裸调用让整站构建失败,报 unrecognized character in shortcode action。)

你应当看到什么:构建一次,页面源码里出现的应该是渲染后的普通文本;如果你在产物里还能搜到裸的定界符,说明这几行被当成真的调用了,构建会随即报错。

第二条禁用项是 Hugo 的短代码占位符前缀字面串。内容里一旦出现这个完整字符串,Hugo 会报

illegal state in content; shortcode token missing end delim

并且错误归因到正在渲染的那个页面上——看起来像那一页有问题,实际是字符串与占位符机制冲突。需要展示时,在中间插入零宽字符打断它;注意实体要写在代码 span 之外,写在反引号里不会被解码,读者会看到实体本身。

本地预览与 GitHub 工作流

先把文档站点跑起来

在改之前先确认「改之前就是好的」。在仓库根目录执行(站点源码就在这一层:hugo.toml、content/、themes/):

bash
hugo --ignoreCache --renderToMemory --quiet
echo $?      # Windows PowerShell 用 $LASTEXITCODE

你应当看到什么:退出码 0,终端没有任何输出(--quiet 会压掉常规信息,但报错与警告仍会显示)。这一步很关键:

想在浏览器里看效果,用 hugo server,然后打开终端提示的地址(默认 http://localhost:1313/)。页脚显示的「最后更新」来自 Git 提交时间(本站开启了 enableGitInfo),所以刚提交过的页面日期会变成这次提交的时间——这是预期行为,不是你改坏了。

完整流程

  1. 派生上游文档仓库(改本站译文时,派生的是本站自己的仓库)。

  2. 克隆你的派生仓库。

  3. 新建分支,分支名要有描述性并包含对应的议题编号(如果有):

    bash
    git checkout -b restructure-foo-page-99999

    你应当看到什么:git branch --show-current 打印出刚建的分支名。到提交前再确认一次自己没在默认分支上改。

  4. 修改文档。

  5. 在本地构建站点,预览你的改动(命令见上一节)。

  6. 提交改动。沿用在开发流程中说明的提交信息约定,但摘要以 content、theme、config、all 或 misc 之一开头,后接冒号、空格,以及以大写字母开头的简短说明;可选地添加引用议题的 Fixes、Closes 行。例如:

    bash
    git 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"
  7. 把新分支推送到你的派生仓库。

  8. 访问文档仓库,创建拉取请求(PR)。

  9. 项目维护者会审查你的 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/ 里能找到对应的产物文件。

本站(中文文档站)的贡献口径

这一段是本地化增补,写的是本站自己的规矩。本站是什么、仓库在哪、规模多大,见参与贡献首页的同一节。

本站欢迎什么样的文档改动

  • 译文修正:错译、漏译、术语不一致、中文语病。译文以对上游英文原文的翻译为准。
  • 教学层增补:补「这一页解决什么问题」、关键步骤后的「你应当看到什么」、按「症状 → 真因 → 怎么修」组织的常见坑表。这是本站与上游直译最大的区别,也是最欢迎的一类改动。
  • 格式与一致性:站内链接、术语、前置元数据是否笔误。
  • 不欢迎的改动:为了让文字「更好看」而删掉上游的命令、参数、默认值、表格、代码块或外链;以及把没有实测依据的结论写成事实。

与上游的三点不同

  1. 不能照抄上游的短代码调用,本站只有 note 与 quick-reference;照抄会让整站构建失败。改写方法与转义写法见转义与短代码。
  2. 前置元数据是本站的六字段契约,字段必须写在表头之前,见前置元数据。
  3. 验收靠脚本,不靠肉眼:.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 修正

更多现象见故障排查;想在上线前给整站做一次体检,见审计。