为 Kubernetes 文档做贡献

Edit This Page

内容组织

本网站使用了 Hugo。在 Hugo 中,内容组织 是一个核心概念。

注意:

Hugo 提示:hugo server --navigateToChanged 命令启动 Hugo 以进行内容编辑会话。

页面列表

页面顺序

文档侧方菜单、文档页面浏览器等以 Hugo 的默认排序顺序列出,它按照权重(从1开始)、日期(最新的排第一个)排序,最后按链接标题排序。

如果你想提升一个页面或一个章节,请在页面头部设置一个较高的权重:

title: My Page
weight: 10
注意:

对于页面的权重,不建议使用连续的数值,比如1、2、3…,而是采用间隔的数值,比如10、20、30…,这样你可以将后续的页面插入到想要的位置。

文档主菜单

Documentation 主菜单是从 docs/ 下面的章节构建的,它在 _index.md 章节内容文件的头部设置了 main_menu 标志:

main_menu: true

注意,链接标题是从页面的 linkTitle 中提取的,因此如果希望它与标题不同,请在内容文件中更改它:

main_menu: true
title: Page Title
linkTitle: Title used in links
注意:

以上每种语言都需要完成。如果在菜单中没有看到你的章节,这可能是因为它没有被 Hugo 标识为一个章节。请在章节对应的目录下创建 _index.md 内容文件。

文档侧方菜单

文档侧方菜单是从 docs/ 下面的 current 章节的 tree 开始构建的。

它将显示所有的章节和它们的页面。

如果你不想列出某个章节或页面,请在页面头部将 toc_hide 标志设置为 true

toc_hide: true

当导航到具有内容的章节时,将显示出指定的章节或页面(例如 _index.md)。否则,将显示该章节里的第一个页面。

文档浏览器

文档主页上的页面浏览器是用 docs section 下一层的所有章节和页面构建的。

如果你不想列出某个章节或页面,请在页面头部将 toc_hide 标志设置为 true

toc_hide: true

主菜单

右上菜单中的网站链接(也在页脚中)是通过页面查找构建的。这是为了确保页面实际存在。因此,如果 case-studies 章节在网站中不存在(按语言),则它将链接不到。

页面包

除了独立的内容页面(Markdown文件),Hugo 还支持 页面包

一个例子是 定制 Hugo 短代码。它被认为是 leaf bundle。目录下的所有内容,包括 index.md,都是包的一部分。这还包括页面相关的链接、可被处理的图像等:

en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json

另一个广泛使用的例子是 includes 包。它在页面头部设置 headless: true,这意味着它没有得到自己的 URL。它只用于其他页面。

en/includes
├── default-storage-class-prereqs.md
├── federated-task-tutorial-prereqs.md
├── federation-content-moved.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md

包中文件的一些重要说明:

  • 对于已翻译的包,任何丢失的非内容文件将从上面的语言继承。这避免了重复。
  • 包中的所有文件都是 Hugo 所指的 Resources,你可以为每种语言提供元数据,例如参数和标题,即使它不支持头部设置(YAML 文件等)。参见页面资源元数据
  • Resource.RelPermalink 中获得的值是页面相关的。参见 Permalinks

样式

本网站的样式表的 SASS 源存储在 src/sass 下面,可以用 make sass 构建(Hugo很快就会得到 SASS 的支持,参见https://github.com/gohugoio/hugo/issues/4243)。

接下来

反馈