[zh] Sync contribution guidelines (3)
This PR is about the changes made to styles.pull/22243/head
Qiming Teng
parent
3f8c9fe65d
commit
200788b0d7
|
|
@ -1,15 +1,13 @@
|
|||
---
|
||||
title: 文档风格概述
|
||||
title: 文档样式概述
|
||||
main_menu: true
|
||||
weight: 80
|
||||
---
|
||||
|
||||
<!--
|
||||
---
|
||||
title: Documentation style overview
|
||||
main_menu: true
|
||||
weight: 80
|
||||
---
|
||||
-->
|
||||
|
||||
<!--
|
||||
|
|
@ -17,5 +15,5 @@ The topics in this section provide guidance on writing style, content formatting
|
|||
and organization, and using Hugo customizations specific to Kubernetes
|
||||
documentation.
|
||||
-->
|
||||
|
||||
本节的主题是提供有关编写风格、内容格式和组织以及使用 Hugo 定制生成 Kubernetes 文档的指导。
|
||||
本节的主题是提供有关写作风格、内容格式和组织以及如何使用
|
||||
特定于 Kubernetes 文档的 Hugo 定制代码的指导。
|
||||
|
|
|
|||
|
|
@ -0,0 +1,142 @@
|
|||
---
|
||||
title: 文档内容指南
|
||||
linktitle: 内容指南
|
||||
content_type: concept
|
||||
weight: 10
|
||||
---
|
||||
<!--
|
||||
title: Documentation Content Guide
|
||||
linktitle: Content guide
|
||||
content_type: concept
|
||||
weight: 10
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
<!--
|
||||
This page contains guidelines for Kubernetes documentation.
|
||||
|
||||
If you have questions about what's allowed, join the #sig-docs channel in
|
||||
[Kubernetes Slack](http://slack.k8s.io/) and ask!
|
||||
|
||||
You can register for Kubernetes Slack at http://slack.k8s.io/.
|
||||
|
||||
For information on creating new content for the Kubernetes
|
||||
docs, follow the [style guide](/docs/contribute/style/style-guide).
|
||||
-->
|
||||
本页包含 Kubernetes 文档的一些指南。
|
||||
|
||||
如果你不清楚哪些事情是可以做的，请加入到
|
||||
[Kubernetes Slack](http://slack.k8s.io/) 的 `#sig-docs` 频道提问！
|
||||
你可以在 http://slack.k8s.io 注册到 Kubernetes Slack。
|
||||
|
||||
关于为 Kubernetes 文档创建新内容的更多信息，可参考
|
||||
[样式指南](/zh/docs/contribute/style/style-guide)。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
<!--
|
||||
## Overview
|
||||
|
||||
Source for the Kubernetes website, including the docs, resides in the
|
||||
[kubernetes/website](https://github.com/kubernetes/website) repository.
|
||||
|
||||
Located in the `kubernetes/website/content/<language_code>/docs` folder, the
|
||||
majority of Kubernetes documentation is specific to the [Kubernetes
|
||||
project](https://github.com/kubernetes/kubernetes).
|
||||
|
||||
## What's allowed
|
||||
|
||||
Kubernetes docs allow content for third-party projects only when:
|
||||
|
||||
- Content documents software in the Kubernetes project
|
||||
- Content documents software that's out of project but necessary for Kubernetes to function
|
||||
- Content is canonical on kubernetes.io, or links to canonical content elsewhere
|
||||
-->
|
||||
## 概述 {#overview}
|
||||
|
||||
Kubernetes 网站（包括其文档）源代码位于
|
||||
[kubernetes/website](https://github.com/kubernetes/website) 仓库中。
|
||||
|
||||
在 `kubernetes/website/content/<语言代码>/docs` 目录下, 绝大多数 Kubernetes
|
||||
文档都是特定于 [Kubernetes 项目](https://github.com/kubernetes/kubernetes)的。
|
||||
|
||||
## 可以发布的内容 {#whats-allowed}
|
||||
|
||||
只有当以下条件满足时，Kuberentes 文档才允许第三方项目的内容：
|
||||
|
||||
- 内容所描述的软件在 Kubernetes 项目内
|
||||
- 内容所描述的软件不在 Kubernetes 项目内，却是让 Kubernetes 正常工作所必需的
|
||||
- 内容是被 kubernetes.io 域名收编的，或者是其他位置的标准典型内容
|
||||
|
||||
<!--
|
||||
### Third party content
|
||||
|
||||
Kubernetes documentation includes applied examples of projects in the Kubernetes project—projects that live in the [kubernetes](https://github.com/kubernetes) and
|
||||
[kubernetes-sigs](https://github.com/kubernetes-sigs) GitHub organizations.
|
||||
|
||||
Links to active content in the Kubernetes project are always allowed.
|
||||
|
||||
Kubernetes requires some third party content to function. Examples include container runtimes (containerd, CRI-O, Docker),
|
||||
[networking policy](/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) (CNI plugins), [Ingress controllers](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/), and [logging](https://kubernetes.io/docs/concepts/cluster-administration/logging/).
|
||||
|
||||
Docs can link to third-party open source software (OSS) outside the Kubernetes project only if it's necessary for Kubernetes to function.
|
||||
-->
|
||||
### 第三方内容 {#third-party-content}
|
||||
|
||||
Kubernetes 文档包含 Kubernetes 项目下的多个项目的应用示例。
|
||||
这里的 Kubernetes 项目指的是 [kubernetes](https://github.com/kubernetes) 和
|
||||
[kubernetes-sigs](https://github.com/kubernetes-sigs) GitHub 组织
|
||||
下的项目。
|
||||
|
||||
链接到 Kubernetes 项目中活跃的内容是一直允许的。
|
||||
|
||||
Kubernetes 需要某些第三方内容才能正常工作。例如
|
||||
容器运行时（containerd、CRI-O、Docker），
|
||||
[联网策略](/zh/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/)
|
||||
（CNI 插件），[Ingress 控制器](/zh/docs/concepts/services-networking/ingress-controllers/)
|
||||
以及[日志](https://kubernetes.io/zh/docs/concepts/cluster-administration/logging/)等。
|
||||
|
||||
只有对应的第三方开源软件（OSS）是运行 Kubernetes 所必需的，才可以在文档中包含
|
||||
指向这些 Kubernetes 项目之外的软件的链接。
|
||||
|
||||
<!--
|
||||
### Dual sourced content
|
||||
|
||||
Wherever possible, Kubernetes docs link to canonical sources instead of hosting
|
||||
dual-sourced content.
|
||||
|
||||
Dual-sourced content requires double the effort (or more!) to maintain
|
||||
and grows stale more quickly.
|
||||
|
||||
{{< note >}}
|
||||
If you're a maintainer for a Kubernetes project and need help hosting your own docs,
|
||||
ask for help in [#sig-docs on Kubernetes Slack](https://kubernetes.slack.com/messages/C1J0BPD2M/).
|
||||
{{< /note >}}
|
||||
-->
|
||||
### 双重来源的内容 {#dual-sourced-content}
|
||||
|
||||
只要有可能，Kubernetes 文档应该指向标准典型的信息源而不是直接托管多重来源的内容。
|
||||
|
||||
双重来源的内容需要双倍（甚至更多）的投入才能维护，而且通常很快就会变得停滞不前。
|
||||
|
||||
{{< note >}}
|
||||
如果你是一个 Kubernetes 项目的维护者，需要帮忙托管你的文档，
|
||||
请在 Kubernetes 的 [#sig-docs 频道](https://kubernetes.slack.com/messages/C1J0BPD2M/)
|
||||
提出请求。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
### More information
|
||||
|
||||
If you have questions about allowed content, join the [Kubernetes Slack](http://slack.k8s.io/) #sig-docs channel and ask!
|
||||
-->
|
||||
### 更多信息 {#more-information}
|
||||
|
||||
如果你对允许出现的内容有疑问，请加入到 [Kubernetes Slack](http://slack.k8s.io/)
|
||||
的 `#sig-docs` 频道提问！
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* 阅读[样式指南](/zh/docs/contribute/style/style-guide)。
|
||||
|
||||
|
||||
|
|
@ -3,99 +3,80 @@ title: 内容组织
|
|||
content_type: concept
|
||||
weight: 40
|
||||
---
|
||||
|
||||
<!--
|
||||
---
|
||||
title: Content organization
|
||||
content_type: concept
|
||||
weight: 40
|
||||
---
|
||||
-->
|
||||
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
This site uses Hugo. In Hugo, [content organization](https://gohugo.io/content-management/organization/) is a core concept.
|
||||
This site uses Hugo. In Hugo, [content
|
||||
organization](https://gohugo.io/content-management/organization/) is a core
|
||||
concept.
|
||||
-->
|
||||
|
||||
本网站使用了 Hugo。在 Hugo 中，[内容组织](https://gohugo.io/content-management/organization/) 是一个核心概念。
|
||||
|
||||
|
||||
|
||||
<!-- body -->
|
||||
|
||||
{{% note %}}
|
||||
<!--
|
||||
**Hugo Tip:** Start Hugo with `hugo server --navigateToChanged` for content edit-sessions.
|
||||
**Hugo Tip:** Start Hugo with `hugo server -navigateToChanged` for content edit-sessions.
|
||||
-->
|
||||
|
||||
**Hugo 提示:** 用 `hugo server --navigateToChanged` 命令启动 Hugo 以进行内容编辑会话。
|
||||
{{% /note %}}
|
||||
{{< note >}}
|
||||
**Hugo 提示：** 用 `hugo server --navigateToChanged` 命令启动 Hugo 以进行内容编辑会话。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
## Page Lists
|
||||
|
||||
### Page Order
|
||||
|
||||
The documentation side menu, the documentation page browser etc. are listed using Hugo's default sort order, which sorts by weight (from 1), date (newest first), and finally by the link title.
|
||||
|
||||
Given that, if you want to move a page or a section up, set a weight in the page's front matter:
|
||||
-->
|
||||
|
||||
## 页面列表
|
||||
|
||||
<!--
|
||||
### Page Order
|
||||
-->
|
||||
|
||||
### 页面顺序
|
||||
|
||||
<!--
|
||||
The documentation side menu, the documentation page browser etc. are listed using Hugo's default sort order, which sorts by weight (from 1), date (newest first), and finally by the link title.
|
||||
-->
|
||||
文档侧方菜单、文档页面浏览器等以 Hugo 的默认排序顺序列出。Hugo 会按照权重（从 1 开始）、
|
||||
日期（最新的排最前面）排序，最后按链接标题排序。
|
||||
|
||||
文档侧方菜单、文档页面浏览器等以 Hugo 的默认排序顺序列出，它按照权重（从1开始）、日期（最新的排第一个）排序，最后按链接标题排序。
|
||||
|
||||
<!--
|
||||
Given that, if you want to move a page or a section up, set a weight in the page's front matter:
|
||||
-->
|
||||
|
||||
如果你想提升一个页面或一个章节，请在页面头部设置一个较高的权重：
|
||||
有鉴于此，如果你想将一个页面或一个章节前移，请在页面头部设置一个较高的权重：
|
||||
|
||||
```yaml
|
||||
title: My Page
|
||||
weight: 10
|
||||
```
|
||||
|
||||
|
||||
{{% note %}}
|
||||
<!--
|
||||
For page weights, it can be smart not to use 1, 2, 3 ..., but some other interval, say 10, 20, 30... This allows you to insert pages where you want later.
|
||||
-->
|
||||
|
||||
对于页面的权重，不建议使用连续的数值，比如1、2、3...，而是采用间隔的数值，比如10、20、30...，这样你可以将后续的页面插入到想要的位置。
|
||||
{{% /note %}}
|
||||
|
||||
{{< note >}}
|
||||
对于页面的权重，不建议使用连续的数值，比如1、2、3...，而应采用间隔的数值，比如10、20、30...
|
||||
这样将来你可以将其他页面插入到想要的位置。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
### Documentation Main Menu
|
||||
-->
|
||||
|
||||
### 文档主菜单
|
||||
|
||||
<!--
|
||||
The `Documentation` main menu is built from the sections below `docs/` with the `main_menu` flag set in front matter of the `_index.md` section content file:
|
||||
-->
|
||||
### 文档主菜单
|
||||
|
||||
`Documentation` 主菜单是从 `docs/` 下面的章节构建的，它在 `_index.md` 章节内容文件的头部设置了 `main_menu` 标志：
|
||||
|
||||
`文档` 主菜单是从 `docs/` 下面的章节构建的。
|
||||
这些章节在其章节内容文件 `_index.md` 的头部设置了 `main_menu` 标志：
|
||||
|
||||
```yaml
|
||||
main_menu: true
|
||||
```
|
||||
|
||||
|
||||
<!--
|
||||
Note that the link title is fetched from the page's `linkTitle`, so if you want it to be something different than the title, change it in the content file:
|
||||
-->
|
||||
|
||||
注意，链接标题是从页面的 `linkTitle` 中提取的，因此如果希望它与标题不同，请在内容文件中更改它：
|
||||
|
||||
注意，链接标题来自页面的 `linkTitle` 字段，因此如果希望它与页面标题不同，请在内容文件中更改它：
|
||||
|
||||
```yaml
|
||||
main_menu: true
|
||||
|
|
@ -103,36 +84,31 @@ title: Page Title
|
|||
linkTitle: Title used in links
|
||||
```
|
||||
|
||||
|
||||
{{% note %}}
|
||||
<!--
|
||||
The above needs to be done per language. If you don't see your section in the menu, it is probably because it is not identified as a section by Hugo. Create a `_index.md` content file in the section folder.
|
||||
-->
|
||||
|
||||
以上每种语言都需要完成。如果在菜单中没有看到你的章节，这可能是因为它没有被 Hugo 标识为一个章节。请在章节对应的目录下创建 `_index.md` 内容文件。
|
||||
{{% /note %}}
|
||||
{{< note >}}
|
||||
以上操作需要为每种语言分别完成。如果在菜单中没有看到你的章节，这可能是因为它没有被 Hugo 识别为一个章节。
|
||||
请在章节对应的目录下创建 `_index.md` 内容文件。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
### Documentation Side Menu
|
||||
-->
|
||||
|
||||
The documentation side-bar menu is built from the _current section tree_ starting below `docs/`.
|
||||
|
||||
It will show all sections and their pages.
|
||||
|
||||
If you don't want to list a section or page, set the `toc_hide` flag to `true` in front matter:
|
||||
|
||||
When you navigate to a section that has content, the specific section or page (e.g. `_index.md`) is shown. Else, the first page inside that section is shown.
|
||||
-->
|
||||
### 文档侧方菜单
|
||||
|
||||
<!--
|
||||
The documentation side-bar menu is built from the _current section tree_ starting below `docs/`.
|
||||
-->
|
||||
文档侧方菜单是基于 `docs/` 下面的 _当前章节的内容树_ 构建的。
|
||||
|
||||
文档侧方菜单是从 `docs/` 下面的 _current 章节的 tree_ 开始构建的。
|
||||
|
||||
<!--
|
||||
It will show all sections and their pages.
|
||||
-->
|
||||
|
||||
它将显示所有的章节和它们的页面。
|
||||
|
||||
<!--
|
||||
If you don't want to list a section or page, set the `toc_hide` flag to `true` in front matter:
|
||||
-->
|
||||
菜单默认显示所有的章节和它们的页面。
|
||||
|
||||
如果你不想列出某个章节或页面，请在页面头部将 `toc_hide` 标志设置为 `true`。
|
||||
|
||||
|
|
@ -140,27 +116,19 @@ If you don't want to list a section or page, set the `toc_hide` flag to `true` i
|
|||
toc_hide: true
|
||||
```
|
||||
|
||||
<!--
|
||||
When you navigate to a section that has content, the specific section or page (e.g. `_index.md`) is shown. Else, the first page inside that section is shown.
|
||||
-->
|
||||
|
||||
当导航到具有内容的章节时，将显示出指定的章节或页面（例如 `_index.md`）。否则，将显示该章节里的第一个页面。
|
||||
当导航到具有内容的章节时，网站将显示出指定的章节或页面（例如 `_index.md`）。
|
||||
否则，将显示该章节里的第一个页面。
|
||||
|
||||
<!--
|
||||
### Documentation Browser
|
||||
-->
|
||||
|
||||
### 文档浏览器
|
||||
|
||||
<!--
|
||||
The page browser on the documentation home page is built using all the sections and pages that are directly below the `docs section`.
|
||||
-->
|
||||
|
||||
文档主页上的页面浏览器是用 `docs section` 下一层的所有章节和页面构建的。
|
||||
|
||||
<!--
|
||||
If you don't want to list a section or page, set the `toc_hide` flag to `true` in front matter:
|
||||
-->
|
||||
### 文档浏览器 {#documentation-browser}
|
||||
|
||||
文档主页上的页面浏览器是基于 `docs section` 下一层的所有章节和页面构建的。
|
||||
|
||||
如果你不想列出某个章节或页面，请在页面头部将 `toc_hide` 标志设置为 `true`。
|
||||
|
||||
|
|
@ -170,34 +138,30 @@ toc_hide: true
|
|||
|
||||
<!--
|
||||
### The Main Menu
|
||||
-->
|
||||
|
||||
### 主菜单
|
||||
|
||||
<!--
|
||||
The site links in the top-right menu -- and also in the footer -- are built by page-lookups. This is to make sure that the page actually exists. So, if the `case-studies` section does not exist in a site (language), it will not be linked to.
|
||||
-->
|
||||
### 主菜单
|
||||
|
||||
右上菜单中的网站链接（也在页脚中）是通过页面查找构建的。这是为了确保页面实际存在。因此，如果 `case-studies` 章节在网站中不存在（按语言），则它将链接不到。
|
||||
|
||||
右上菜单中的网站链接（也出现在页脚中）是通过页面查找构建的。
|
||||
这是为了确保页面实际存在。因此，如果 `case-studies` 章节在网站（或者其本地化版本）中不存在，
|
||||
则不会出现对应的链接。
|
||||
|
||||
<!--
|
||||
## Page Bundles
|
||||
-->
|
||||
|
||||
## 页面包
|
||||
|
||||
<!--
|
||||
In addition to standalone content pages (Markdown files), Hugo supports [Page Bundles](https://gohugo.io/content-management/page-bundles/).
|
||||
-->
|
||||
|
||||
除了独立的内容页面（Markdown文件），Hugo 还支持 [页面包](https://gohugo.io/content-management/page-bundles/)。
|
||||
|
||||
<!--
|
||||
One example is [Custom Hugo Shortcodes](/docs/contribute/style/hugo-shortcodes/). It is considered a `leaf bundle`. Everything below the directory, including the `index.md`, will be part of the bundle. This also includes page-relative links, images that can be processed etc.:
|
||||
-->
|
||||
## 页面包
|
||||
|
||||
一个例子是 [定制 Hugo 短代码](/docs/contribute/style/hugo-shortcodes/)。它被认为是 `leaf bundle`。目录下的所有内容，包括 `index.md`，都是包的一部分。这还包括页面相关的链接、可被处理的图像等：
|
||||
除了独立的内容页面（Markdown 文件），Hugo 还支持
|
||||
[页面包](https://gohugo.io/content-management/page-bundles/)。
|
||||
|
||||
一个例子是[定制的 Hugo 短代码（shortcodes）](/zh/docs/contribute/style/hugo-shortcodes/)。
|
||||
它被认为是 `leaf bundle`（叶子包）。
|
||||
目录下的所有内容，包括 `index.md`，都是包的一部分。此外还包括页面间相对链接、可被处理的图像等：
|
||||
|
||||
```bash
|
||||
en/docs/home/contribute/includes
|
||||
|
|
@ -210,8 +174,8 @@ en/docs/home/contribute/includes
|
|||
<!--
|
||||
Another widely used example is the `includes` bundle. It sets `headless: true` in front matter, which means that it does not get its own URL. It is only used in other pages.
|
||||
-->
|
||||
|
||||
另一个广泛使用的例子是 `includes` 包。它在页面头部设置 `headless: true`，这意味着它没有得到自己的 URL。它只用于其他页面。
|
||||
另一个广泛使用的例子是 `includes` 包。
|
||||
这类包在页面头部设置 `headless: true`，意味着它没有得到自己的 URL。它只用于其他页面。
|
||||
|
||||
```bash
|
||||
en/includes
|
||||
|
|
@ -228,44 +192,39 @@ en/includes
|
|||
|
||||
<!--
|
||||
Some important notes to the files in the bundles:
|
||||
-->
|
||||
|
||||
包中文件的一些重要说明：
|
||||
|
||||
<!--
|
||||
* For translated bundles, any missing non-content files will be inherited from languages above. This avoids duplication.
|
||||
* All the files in a bundle are what Hugo calls `Resources` and you can provide metadata per language, such as parameters and title, even if it does not supports front matter (YAML files etc.). See [Page Resources Metadata](https://gohugo.io/content-management/page-resources/#page-resources-metadata).
|
||||
* The value you get from `.RelPermalink` of a `Resource` is page-relative. See [Permalinks](https://gohugo.io/content-management/urls/#permalinks).
|
||||
-->
|
||||
有关包中文件的一些重要说明：
|
||||
|
||||
* 对于已翻译的包，任何丢失的非内容文件将从上面的语言继承。这避免了重复。
|
||||
* 包中的所有文件都是 Hugo 所指的 `Resources`，你可以为每种语言提供元数据，例如参数和标题，即使它不支持头部设置（YAML 文件等）。参见[页面资源元数据](https://gohugo.io/content-management/page-resources/#page-resources-metadata)。
|
||||
* 从 `Resource` 的 `.RelPermalink` 中获得的值是页面相关的。参见 [Permalinks](https://gohugo.io/content-management/urls/#permalinks)。
|
||||
|
||||
* 已翻译的包会从上面的语言继承所有缺失的、非内容文件。这一设计可以避免重复。
|
||||
* 包中的所有文件都是 Hugo 所指的 `Resources`，你可以为用不同语言为其提供元数据，
|
||||
例如参数和标题，即使它不支持头部设置（YAML 文件等）。
|
||||
参见[页面资源元数据](https://gohugo.io/content-management/page-resources/#page-resources-metadata)。
|
||||
* 从 `Resource` 的 `.RelPermalink` 中获得的值是相对于当前页面的。
|
||||
参见 [Permalinks](https://gohugo.io/content-management/urls/#permalinks)。
|
||||
|
||||
<!--
|
||||
## Styles
|
||||
-->
|
||||
|
||||
## 样式
|
||||
|
||||
<!--
|
||||
The `SASS` source of the stylesheets for this site is stored below `src/sass` and can be built with `make sass` (note that Hugo will get `SASS` support soon, see https://github.com/gohugoio/hugo/issues/4243).
|
||||
-->
|
||||
## 样式 {#styles}
|
||||
|
||||
本网站的样式表的 `SASS` 源存储在 `src/sass` 下面，可以用 `make sass` 构建（Hugo很快就会得到 `SASS` 的支持，参见https://github.com/gohugoio/hugo/issues/4243）。
|
||||
|
||||
|
||||
网站的样式表的 `SASS` 源文件存储在 `src/sass` 下面，可以用 `make sass` 构建
|
||||
（Hugo 很快就提供 `SASS` 的支持，参见 https://github.com/gohugoio/hugo/issues/4243）。
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
|
||||
<!--
|
||||
* [Custom Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/)
|
||||
* [Style guide](/docs/contribute/style/style-guide)
|
||||
* Learn about [custom Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/)
|
||||
* Learn about the [Style guide](/docs/contribute/style/style-guide)
|
||||
* Learn about the [Content guide](/docs/contribute/style/content-guide)
|
||||
-->
|
||||
|
||||
* [定制 Hugo 短代码](/docs/contribute/style/hugo-shortcodes/)
|
||||
* [样式指南](/docs/contribute/style/style-guide)
|
||||
|
||||
* 了解[定制 Hugo 短代码](/zh/docs/contribute/style/hugo-shortcodes/)
|
||||
* 了解[样式指南](/zh/docs/contribute/style/style-guide)
|
||||
* 了解[内容指南](/zh/docs/contribute/style/content-guide)
|
||||
|
||||
|
|
|
|||
|
|
@ -3,21 +3,18 @@ title: 例子 #1
|
|||
---
|
||||
|
||||
<!--
|
||||
---
|
||||
title: Example #1
|
||||
---
|
||||
-->
|
||||
|
||||
<!--
|
||||
This is an **example** content file inside the **includes** leaf bundle.
|
||||
-->
|
||||
|
||||
这是一个内容文件**示例**，位于一个**includes**叶子包中。
|
||||
|
||||
{{< note >}}
|
||||
<!--
|
||||
Included content files can also contain shortcodes.
|
||||
-->
|
||||
{{< note >}}
|
||||
被包含的内容文件也可以包含短代码。
|
||||
{{< /note >}}
|
||||
|
||||
包含的内容文件也可以包含短代码。
|
||||
{{< /note >}}
|
||||
|
|
@ -1,17 +1,12 @@
|
|||
---
|
||||
title: 例子 #1
|
||||
---
|
||||
|
||||
<!--
|
||||
---
|
||||
title: Example #1
|
||||
---
|
||||
-->
|
||||
|
||||
<!--
|
||||
This is another **example** content file inside the **includes** leaf bundle.
|
||||
-->
|
||||
|
||||
这是另一个内容文件**示例**，位于一个**includes**叶子包中。
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,37 +1,41 @@
|
|||
---
|
||||
approvers:
|
||||
- chenopis
|
||||
title: 定制 Hugo 短代码
|
||||
content_type: concept
|
||||
---
|
||||
|
||||
<!-- ---
|
||||
approvers:
|
||||
- chenopis
|
||||
<!--
|
||||
title: Custom Hugo Shortcodes
|
||||
content_type: concept
|
||||
--- -->
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!-- This page explains the custom Hugo shortcodes that can be used in Kubernetes markdown documentation. -->
|
||||
本页面将介绍定制 Hugo 短代码，可以用于 Kubernetes markdown 文档书写。
|
||||
|
||||
<!-- Read more about shortcodes in the [Hugo documentation](https://gohugo.io/content-management/shortcodes). -->
|
||||
更多关于短代码参见 [Hugo 文档](https://gohugo.io/content-management/shortcodes)。
|
||||
|
||||
关于短代码的更多信息可参见 [Hugo 文档](https://gohugo.io/content-management/shortcodes)。
|
||||
|
||||
<!-- body -->
|
||||
<!-- ## Feature state -->
|
||||
|
||||
<!--
|
||||
## Feature state
|
||||
|
||||
In a markdown page (.md file) on this site, you can add a shortcode to display
|
||||
version and state of the documented feature.
|
||||
-->
|
||||
## 功能状态
|
||||
|
||||
<!-- In a markdown page (.md file) on this site, you can add a shortcode to display version and state of the documented feature. -->
|
||||
本站上面的 markdown 页面，你可以加入短代码来展示已经文档介绍的功能的版本和状态(state)。
|
||||
在本站的 markdown 页面中，你可以加入短代码来展示所描述的功能特性的版本和状态。
|
||||
|
||||
<!-- ### Feature state demo -->
|
||||
### 功能状态演示
|
||||
<!--
|
||||
### Feature state demo
|
||||
|
||||
<!-- Below is a demo of the feature state snippet, which displays the feature as stable in Kubernetes version 1.10. -->
|
||||
下面是一个功能状态代码段的演示，表明这个功能已经在 Kubernetes v1.10时就已经稳定了。
|
||||
Below is a demo of the feature state snippet, which displays the feature as stable
|
||||
in Kubernetes version 1.10.
|
||||
-->
|
||||
### 功能状态示例
|
||||
|
||||
下面是一个功能状态代码段的演示，表明这个功能已经在 Kubernetes v1.10 时就已经稳定了。
|
||||
|
||||
```
|
||||
{{</* feature-state for_k8s_version="v1.10" state="stable" */>}}
|
||||
|
|
@ -43,32 +47,33 @@ content_type: concept
|
|||
{{< feature-state for_k8s_version="v1.10" state="stable" >}}
|
||||
|
||||
<!-- The valid values for `state` are: -->
|
||||
`state`的可选值如下：
|
||||
`state` 的可选值如下：
|
||||
|
||||
* alpha
|
||||
* beta
|
||||
* deprecated
|
||||
* stable
|
||||
|
||||
<!-- ### Feature state code -->
|
||||
<!--
|
||||
### Feature state code
|
||||
|
||||
The displayed Kubernetes version defaults to that of the page or the site.
|
||||
This can be changed by passing the <code>for_k8s_version</code> shortcode
|
||||
parameter.
|
||||
-->
|
||||
### 功能状态代码
|
||||
|
||||
<!-- Below is the template code for each available feature state. -->
|
||||
下面是为每个现有的功能状态的模板代码。
|
||||
|
||||
<!-- The displayed Kubernetes version defaults to that of the page or the site. This can be changed by passing the <code>for_k8s_version</code> shortcode parameter. -->
|
||||
|
||||
显示的 Kubernetes 默认为该页或站点版本。
|
||||
这个可以通过修改 <code>for_k8s_version</code> 短代码参数来调整。
|
||||
所显示的 Kubernetes 默认为该页或站点版本。
|
||||
可以通过修改 <code>for_k8s_version</code> 短代码参数来调整要显示的版本。
|
||||
|
||||
```
|
||||
{{</* feature-state for_k8s_version="v1.10" state="stable" */>}}
|
||||
{{</* feature-state for_k8s_version="v1.11" state="stable" */>}}
|
||||
```
|
||||
|
||||
<!-- Renders to: -->
|
||||
会转换为：
|
||||
|
||||
{{< feature-state for_k8s_version="v1.10" state="stable" >}}
|
||||
{{< feature-state for_k8s_version="v1.11" state="stable" >}}
|
||||
|
||||
<!-- #### Alpha feature -->
|
||||
#### Alpha 功能
|
||||
|
|
@ -82,7 +87,6 @@ content_type: concept
|
|||
|
||||
{{< feature-state state="alpha" >}}
|
||||
|
||||
|
||||
<!-- #### Beta feature -->
|
||||
#### Beta 功能
|
||||
|
||||
|
|
@ -119,63 +123,165 @@ content_type: concept
|
|||
|
||||
{{< feature-state state="deprecated" >}}
|
||||
|
||||
<!-- ## Glossary -->
|
||||
<!--
|
||||
## Glossary
|
||||
|
||||
You can reference glossary terms with an inclusion that will automatically
|
||||
update and replace content with the relevant links from [our
|
||||
glossary](/docs/reference/glossary/). When the term is moused-over by someone
|
||||
using the online documentation, the glossary entry will display a tooltip.
|
||||
-->
|
||||
## 词汇
|
||||
|
||||
<!-- You can reference glossary terms with an inclusion that will automatically update and replace content with the relevant links from [our glossary](/docs/reference/glossary/). When the term is moused-over by someone
|
||||
using the online documentation, the glossary entry will display a tooltip. -->
|
||||
|
||||
你可以通过加入术语词汇的短代码，来自动更新和替换相应链接中的内容（[我们的词汇库](/docs/reference/glossary/)）
|
||||
你可以通过加入术语词汇的短代码，来自动更新和替换相应链接中的内容
|
||||
（[我们的词汇库](/zh/docs/reference/glossary/)）
|
||||
这样，在浏览在线文档，鼠标移到术语上时，术语解释就会显示在提示框中。
|
||||
|
||||
<!-- The raw data for glossary terms is stored at [https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary](https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary), with a content file for each glossary term. -->
|
||||
<!--
|
||||
The raw data for glossary terms is stored at [https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary](https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary), with a content file for each glossary term.
|
||||
-->
|
||||
|
||||
词汇术语的原始数据保存在 [https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary](https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary)，每个内容文件对应相应的术语解释。
|
||||
|
||||
<!-- ### Glossary Demo -->
|
||||
<!--
|
||||
### Glossary Demo
|
||||
|
||||
For example, the following include within the markdown will render to
|
||||
{{< glossary_tooltip text="cluster" term_id="cluster" >}} with a tooltip:
|
||||
-->
|
||||
### 词汇演示
|
||||
|
||||
<!-- For example, the following include within the markdown will render to {{< glossary_tooltip text="cluster" term_id="cluster" >}} with a tooltip: -->
|
||||
例如，下面的代码在 markdown 中将会转换为 `{{< glossary_tooltip text="cluster" term_id="cluster" >}}`，
|
||||
然后在提示框中显示。
|
||||
|
||||
例如，下面的代码在 markdown 中将会转换为 `{{< glossary_tooltip text="cluster" term_id="cluster" >}}`，然后在提示框中显示。
|
||||
|
||||
````liquid
|
||||
```liquid
|
||||
{{</* glossary_tooltip text="cluster" term_id="cluster" */>}}
|
||||
````
|
||||
```
|
||||
|
||||
<!-- ## Tabs -->
|
||||
## 标签页
|
||||
<!--
|
||||
## Table captions
|
||||
|
||||
<!-- In a markdown page (`.md` file) on this site, you can add a tab set to display multiple flavors of a given solution. -->
|
||||
在本站的 markdown 页面（`.md` 文件）中，你可以加入一个标签页集来显示不同形式的解决方案。
|
||||
|
||||
<!-- The `tabs` shortcode takes these parameters: -->
|
||||
标签页的短代码包含以下参数：
|
||||
|
||||
<!-- * `name`: The name as shown on the tab.
|
||||
* `codelang`: If you provide inner content to the `tab` shortcode, you can tell Hugo what code language to use for highlighting.
|
||||
* `include`: The file to include in the tab. If the tab lives in a Hugo [leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles), the file -- which can be any MIME type supported by Hugo -- will be looked up in the bundle itself. If not, the content page to include will be looked up relative to the current. Note that with the `include` you will not have any shortcode inner content and must use the self-closing syntax, e.g. {{</* tab name="Content File #1" include="example1" /*/>}}. Non-content files will be code-highlighted. The language to use will be taken from the filename if not provided in `codelang`. -->
|
||||
|
||||
* `name`: 标签页上的名字。
|
||||
* `codelang`: 如果要在`tab`短代码中加入内部内容，需要告知 Hugo 使用的是什么代码语言，方便代码高亮。
|
||||
* `include`: 标签页中所要包含的文件。如果标签页是在 Hugo 的页面包（[leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles)）中，文件（可以是 Hugo 所支持的 MIME 类型文件）将会在包中查找。如果不是，所要包含的内容页面将会在当前路径的相关路径下查找。注意，在`include`属性部分，不能加入短代码内部内容，必须要使用自结束（self-closing）的语法。
|
||||
非内容文件将会被代码高亮。如果没有在`codelang`进行声明的话，所用的代码语言将会来自文件名。
|
||||
|
||||
<!-- * If your inner content is markdown, you must use `%`-delimiter to surorund the tab, e.g. `{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`
|
||||
* You can combine the variations mentioned above inside a tab set. -->
|
||||
|
||||
* 如果内部内容是 markdown， 你必须要使用 `%` 分隔符来包装标签页，例如，`{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`
|
||||
* 可以在标签页集中混合使用上面的各种变形。
|
||||
|
||||
<!-- Below is a demo of the tabs shortcode. -->
|
||||
下面是演示标签页短代码。
|
||||
You can make tables more accessible to screen readers by adding a table caption. To add a [caption](https://www.w3schools.com/tags/tag_caption.asp) to a table, enclose the table with a `table` shortcode and specify the caption with the `caption` parameter.
|
||||
|
||||
{{< note >}}
|
||||
The tab **name** in a `tabs` definition must be unique within a content page.
|
||||
一个内容页面下的，标签页定义中的标签页 **名** 必须是唯一的。
|
||||
Table captions are visible to screen readers but invisible when viewed in standard HTML.
|
||||
{{< /note >}}
|
||||
|
||||
<!-- ### Tabs demo: Code highlighting -->
|
||||
Here's an example:
|
||||
-->
|
||||
## 表格标题 {#table-captions}
|
||||
|
||||
通过添加表格标题，你可以让表格能够被屏幕阅读器读取。
|
||||
要向表格添加[标题（Caption）](https://www.w3schools.com/tags/tag_caption.asp)，
|
||||
可用 `table` 短代码包围表格定义，并使用 `caption` 参数给出表格标题。
|
||||
|
||||
{{< note >}}
|
||||
表格标题对屏幕阅读器是可见的，但在标准 HTML 中查看时是不可见的。
|
||||
{{< /note >}}
|
||||
|
||||
下面是一个例子：
|
||||
|
||||
<!--
|
||||
|
||||
```go-html-template
|
||||
{{</* table caption="Configuration parameters" >}}
|
||||
Parameter | Description | Default
|
||||
`timeout` | The timeout for requests | `30s`
|
||||
`logLevel` | The log level for log output | `INFO`
|
||||
{{< /table */>}}
|
||||
|
||||
The rendered table looks like this:
|
||||
|
||||
{{< table caption="Configuration parameters" >}}
|
||||
Parameter | Description | Default
|
||||
`timeout` | The timeout for requests | `30s`
|
||||
`logLevel` | The log level for log output | `INFO`
|
||||
{{< /table >}}
|
||||
-->
|
||||
|
||||
```go-html-template
|
||||
{{</* table caption="配置参数" >}}
|
||||
参数 | 描述 | 默认值
|
||||
:---------|:------------|:-------
|
||||
`timeout` | 请求的超时时长 | `30s`
|
||||
`logLevel` | 日志输出的级别 | `INFO`
|
||||
{{< /table */>}}
|
||||
```
|
||||
|
||||
所渲染的表格如下：
|
||||
|
||||
{{< table caption="配置参数" >}}
|
||||
参数 | 描述 | 默认值
|
||||
:---------|:------------|:-------
|
||||
`timeout` | 请求的超时时长 | `30s`
|
||||
`logLevel` | 日志输出的级别 | `INFO`
|
||||
{{< /table >}}
|
||||
|
||||
<!--
|
||||
If you inspect the HTML for the table, you should see this element immediately after the opening `<table>` element:
|
||||
|
||||
```html
|
||||
<caption style="display: none;">Configuration parameters</caption>
|
||||
```
|
||||
-->
|
||||
如果你查看表格的 HTML 输出结果，你会看到 `<table>` 元素
|
||||
后面紧接着下面的元素：
|
||||
|
||||
```html
|
||||
<caption style="display: none;">配置参数</caption>
|
||||
```
|
||||
|
||||
<!--
|
||||
## Tabs
|
||||
|
||||
In a markdown page (`.md` file) on this site, you can add a tab set to display
|
||||
multiple flavors of a given solution.
|
||||
|
||||
The `tabs` shortcode takes these parameters:
|
||||
-->
|
||||
## 标签页
|
||||
|
||||
在本站的 markdown 页面（`.md` 文件）中，你可以加入一个标签页集来显示
|
||||
某解决方案的不同形式。
|
||||
|
||||
标签页的短代码包含以下参数：
|
||||
|
||||
<!--
|
||||
* `name`: The name as shown on the tab.
|
||||
* `codelang`: If you provide inner content to the `tab` shortcode, you can tell Hugo what code language to use for highlighting.
|
||||
* `include`: The file to include in the tab. If the tab lives in a Hugo [leaf bundle](https://gohugo.io/content-management/page-bundles/#leaf-bundles), the file -- which can be any MIME type supported by Hugo -- will be looked up in the bundle itself. If not, the content page to include will be looked up relative to the current. Note that with the `include` you will not have any shortcode inner content and must use the self-closing syntax, e.g. {{</* tab name="Content File #1" include="example1" /*/>}}. Non-content files will be code-highlighted. The language to use will be taken from the filename if not provided in `codelang`.
|
||||
-->
|
||||
* `name`： 标签页上显示的名字。
|
||||
* `codelang`: 如果要在 `tab` 短代码中加入内部内容，需要告知 Hugo 使用的是什么代码语言，方便代码高亮。
|
||||
* `include`: 标签页中所要包含的文件。如果标签页是在 Hugo 的
|
||||
[叶子包](https://gohugo.io/content-management/page-bundles/#leaf-bundles)中定义，
|
||||
Hugo 会在包内查找文件（可以是 Hugo 所支持的任何 MIME 类型文件）。
|
||||
否则，Hugo 会在当前路径的相对路径下查找所要包含的内容页面。
|
||||
注意，在 `include` 页面中不能包含短代码内容，必须要使用自结束（self-closing）语法。
|
||||
非内容文件将会被代码高亮。
|
||||
如果没有在 `codelang` 进行声明的话，Hugo 会根据文件名推测所用的语言。
|
||||
<!--
|
||||
* If your inner content is markdown, you must use `%`-delimiter to surorund the tab, e.g. `{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`
|
||||
* You can combine the variations mentioned above inside a tab set.
|
||||
-->
|
||||
* 如果内部内容是 Markdown，你必须要使用 `%` 分隔符来包装标签页。
|
||||
例如，`{{%/* tab name="Tab 1" %}}This is **markdown**{{% /tab */%}}`。
|
||||
* 可以在标签页集中混合使用上面的各种变形。
|
||||
|
||||
<!--
|
||||
Below is a demo of the tabs shortcode.
|
||||
|
||||
The tab **name** in a `tabs` definition must be unique within a content page.
|
||||
-->
|
||||
下面是标签页短代码的示例。
|
||||
|
||||
{{< note >}}
|
||||
内容页面下的 **tabs** 定义中的标签页 **name** 必须是唯一的。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
### Tabs demo: Code highlighting
|
||||
-->
|
||||
### 标签页演示：代码高亮
|
||||
|
||||
```go-text-template
|
||||
|
|
@ -255,20 +361,17 @@ println "This is tab 2."
|
|||
{{< tab name="JSON File" include="podtemplate" />}}
|
||||
{{< /tabs >}}
|
||||
|
||||
|
||||
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
<!-- * Learn about [Hugo](https://gohugo.io/).
|
||||
* Learn about [writing a new topic](/docs/home/contribute/write-new-topic/).
|
||||
* Learn about [using page templates](/docs/home/contribute/page-templates/).
|
||||
* Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/)
|
||||
* Learn about [creating a pull request](/docs/home/contribute/create-pull-request/). -->
|
||||
<!--
|
||||
* Learn about [Hugo](https://gohugo.io/).
|
||||
* Learn about [writing a new topic](/docs/home/contribute/style/write-new-topic/).
|
||||
* Learn about [page content types](/docs/home/contribute/style/page-content-types/).
|
||||
* Learn about [creating a pull request](/docs/home/contribute/create-pull-request/).
|
||||
-->
|
||||
|
||||
* 了解 [Hugo](https://gohugo.io/)。
|
||||
* 了解 [撰写新的话题](/docs/home/contribute/write-new-topic/)。
|
||||
* 了解 [使用页面模板](/docs/home/contribute/page-templates/)。
|
||||
* 了解 [暂存修改](/docs/home/contribute/stage-documentation-changes/)。
|
||||
* 了解 [创建 pull request](/docs/home/contribute/create-pull-request/)。
|
||||
* 了解 [撰写新的话题](/zh/docs/contribute/write-new-topic/)。
|
||||
* 了解 [使用页面类型](/zh/docs/contribute/style/page-content-types/)。
|
||||
* 了解 [发起 PR](/zh/docs/contribute/new-content/create-a-pr/)。
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,412 @@
|
|||
---
|
||||
title: 页面内容类型
|
||||
content_type: concept
|
||||
weight: 30
|
||||
card:
|
||||
name: 贡献
|
||||
weight: 30
|
||||
---
|
||||
<!--
|
||||
title: Page content types
|
||||
content_type: concept
|
||||
weight: 30
|
||||
card:
|
||||
name: contribute
|
||||
weight: 30
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
The Kubernetes documentation follows several types of page content:
|
||||
|
||||
- Concept
|
||||
- Task
|
||||
- Tutorial
|
||||
- Reference
|
||||
-->
|
||||
Kubernetes 文档包含以下几种页面内容类型：
|
||||
|
||||
- 概念（Concept）
|
||||
- 任务（Task）
|
||||
- 教程（Tutorial）
|
||||
- 参考（Reference）
|
||||
|
||||
<!-- body -->
|
||||
|
||||
<!--
|
||||
## Content sections
|
||||
|
||||
Each page content type contains a number of sections defined by
|
||||
Markdown comments and HTML headings. You can add content headings to
|
||||
your page with the `heading` shortcode. The comments and headings help
|
||||
maintain the structure of the page content types.
|
||||
|
||||
Examples of Markdown comments defining page content sections:
|
||||
-->
|
||||
## 内容章节 {#content-sections}
|
||||
|
||||
每种页面内容类型都有一些使用 Markdown 注释和 HTML 标题定义的章节。
|
||||
你可以使用 `heading` 短代码将内容标题添加到你的页面中。
|
||||
注释和标题有助于维护对应页面内容类型的结构组织。
|
||||
|
||||
定义页面内容章节的 Markdown 注释示例：
|
||||
|
||||
```markdown
|
||||
<!-- overview -->
|
||||
```
|
||||
|
||||
```markdown
|
||||
<!-- body -->
|
||||
```
|
||||
|
||||
<!--
|
||||
To create common headings in your content pages, use the `heading` shortcode with
|
||||
a heading string.
|
||||
|
||||
Examples of heading strings:
|
||||
|
||||
- whatsnext
|
||||
- prerequisites
|
||||
- objectives
|
||||
- cleanup
|
||||
- synopsis
|
||||
- seealso
|
||||
- options
|
||||
|
||||
For example, to create a `whatsnext` heading, add the heading shortcode with the "whatsnext" string:
|
||||
-->
|
||||
要在内容页面中创建通用的标题，可以使用 `heading` 短代码加上标题字符串。
|
||||
|
||||
标题字符串示例：
|
||||
|
||||
- whatsnext
|
||||
- prerequisites
|
||||
- objectives
|
||||
- cleanup
|
||||
- synopsis
|
||||
- seealso
|
||||
- options
|
||||
|
||||
例如，要创建一个 `whatsnext` 标题，添加 heading 短代码并指定 "whatsnext" 字符串：
|
||||
|
||||
```none
|
||||
## {{%/* heading "whatsnext" */%}}
|
||||
```
|
||||
|
||||
<!--
|
||||
You can declare a `prerequisites` heading as follows:
|
||||
-->
|
||||
你可以像下面这样声明一个 `prerequisites` 标题：
|
||||
|
||||
```none
|
||||
## {{%/* heading "prerequisites" */%}}
|
||||
```
|
||||
|
||||
<!--
|
||||
The `heading` shortcode expects one string parameter.
|
||||
The heading string parameter matches the prefix of a variable in the `i18n/<lang>.toml` files.
|
||||
For example:
|
||||
-->
|
||||
短代码 `heading` 需要一个字符串参数。
|
||||
该字符串参数要与 `i18n/<语言>.toml` 文件中以其为前缀的某个变量匹配。
|
||||
例如：
|
||||
|
||||
`i18n/en.toml`:
|
||||
|
||||
```toml
|
||||
[whatsnext_heading]
|
||||
other = "What's next"
|
||||
```
|
||||
|
||||
`i18n/ko.toml`:
|
||||
|
||||
```toml
|
||||
[whatsnext_heading]
|
||||
other = "다음 내용"
|
||||
```
|
||||
|
||||
<!--
|
||||
## Content types
|
||||
|
||||
Each content type informally defines its expected page structure.
|
||||
Create page content with the suggested page sections.
|
||||
-->
|
||||
## 内容类型 {#content-types}
|
||||
|
||||
每种内容类型都非正式地定义了期望的页面结构组织。
|
||||
请按照所建议的页面章节来创建内容页面。
|
||||
|
||||
<!--
|
||||
### Concept
|
||||
|
||||
A concept page explains some aspect of Kubernetes. For example, a concept
|
||||
page might describe the Kubernetes Deployment object and explain the role it
|
||||
plays as an application once it is deployed, scaled, and updated. Typically, concept
|
||||
pages don't include sequences of steps, but instead provide links to tasks or
|
||||
tutorials.
|
||||
|
||||
To write a new concept page, create a Markdown file in a subdirectory of the
|
||||
`/content/en/docs/concepts` directory, with the following characteristics:
|
||||
|
||||
Concept pages are divided into three sections:
|
||||
|
||||
| Page section |
|
||||
|----------------|
|
||||
| overview |
|
||||
| body |
|
||||
| whatsnext |
|
||||
-->
|
||||
### 概念 {#concept}
|
||||
|
||||
概念页面用来解释 Kubernetes 的某些方面。例如，概念页面可以用来描述 Kubernetes
|
||||
中的 Deployment 对象，解释其作为应用的角色如何部署、扩缩和更新。
|
||||
通常，概念页面不需要包含步骤序列，但包含指向任务或教程的链接。
|
||||
|
||||
要编写一个新的概念页面，在 `/content/en/docs/concepts` 目录下面的子目录中新建
|
||||
一个 Markdown 文件。该文件具有以下特点。
|
||||
|
||||
概念页面分为三个章节：
|
||||
|
||||
| 页面章节 |
|
||||
|--------------------|
|
||||
| overview （概述） |
|
||||
| body (主体） |
|
||||
| whatsnext (接下来）|
|
||||
|
||||
<!--
|
||||
The `overview` and `body` sections appear as comments in the concept page.
|
||||
You can add the `whatsnext` section to your page with the `heading` shortcode.
|
||||
|
||||
Fill each section with content. Follow these guidelines:
|
||||
|
||||
- Organize content with H2 and H3 headings.
|
||||
- For `overview`, set the topic's context with a single paragraph.
|
||||
- For `body`, explain the concept.
|
||||
- For `whatsnext`, provide a bulleted list of topics (5 maximum) to learn more about the concept.
|
||||
|
||||
[Annotations](/docs/concepts/overview/working-with-objects/annotations/) is a
|
||||
published example of a concept page.
|
||||
-->
|
||||
其中的 `overview` 和 `body` 章节在概念页面中显示为注释。
|
||||
你可以使用 `heading` 短代码向页面添加 `wahtsnext` 节。
|
||||
|
||||
在为每个章节撰写内容时，遵从一些规定：
|
||||
|
||||
- 使用二级和三级标题（H2、H3）来组织内容
|
||||
- 在 `overview` 节中，使用一段文字来为主体部分铺陈上下文；
|
||||
- 在 `body` 节中，详细解释对应概念；
|
||||
- 对于 `whatsnext` 节，提供一个项目符号列表（最多 5 个），帮助读者进一步学习掌握概念
|
||||
|
||||
[注解](/zh/docs/concepts/overview/working-with-objects/annotations/)页面是一个已经
|
||||
上线的概念页面的例子。
|
||||
|
||||
<!--
|
||||
### Task
|
||||
|
||||
A task page shows how to do a single thing, typically by giving a short
|
||||
sequence of steps. Task pages have minimal explanation, but often provide links
|
||||
to conceptual topics that provide related background and knowledge.
|
||||
|
||||
To write a new task page, create a Markdown file in a subdirectory of the
|
||||
`/content/en/docs/tasks` directory, with the following characteristics:
|
||||
|
||||
| Page section |
|
||||
|----------------|
|
||||
| overview |
|
||||
| prerequisites |
|
||||
| steps |
|
||||
| discussion |
|
||||
| whatsnext |
|
||||
-->
|
||||
### 任务（Task） {#task}
|
||||
|
||||
任务页面讲解如何完成某项工作，通常包含由为数不多的几个步骤组成的序列。
|
||||
任务页面的讲解文字很少，不过通常会包含指向概念主题的链接，以便读者
|
||||
能够了解相关的背景和知识。
|
||||
|
||||
编写新的任务页面时，在 `/content/en/docs/tasks` 目录下的子目录中创建一个
|
||||
新的 Markdown 文件。该文件特点如下。
|
||||
|
||||
| 页面章节 |
|
||||
|---------------------------|
|
||||
| overview （概述） |
|
||||
| prerequisites （准备工作）|
|
||||
| steps （步骤） |
|
||||
| discussion （讨论） |
|
||||
| whatsnext （接下来） |
|
||||
|
||||
<!--
|
||||
The `overview`, `steps`, and `discussion` sections appear as comments in the task page.
|
||||
You can add the `prerequisites` and `whatsnext` sections to your page
|
||||
with the `heading` shortcode.
|
||||
|
||||
Within each section, write your content. Use the following guidelines:
|
||||
|
||||
- Use a minimum of H2 headings (with two leading `#` characters). The sections
|
||||
themselves are titled automatically by the template.
|
||||
- For `overview`, use a paragraph to set context for the entire topic.
|
||||
- For `prerequisites`, use bullet lists when possible. Start adding additional
|
||||
prerequisites below the `include`. The default prerequisites include a running Kubernetes cluster.
|
||||
- For `steps`, use numbered lists.
|
||||
- For discussion, use normal content to expand upon the information covered
|
||||
in `steps`.
|
||||
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
|
||||
interested in reading next.
|
||||
|
||||
An example of a published task topic is [Using an HTTP proxy to access the Kubernetes API](/docs/tasks/extend-kubernetes/http-proxy-access-api/).
|
||||
-->
|
||||
其中的 `overview`、`steps` 和 `discussion` 节在任务页面中显示为注释。
|
||||
你可以使用 `heading` 短代码添加 `prerequisites` 和 `whatsnext` 小节。
|
||||
|
||||
在每个小节内撰写内容时注意以下规定：
|
||||
|
||||
- 最低使用二级标题（H2，标题行前带两个 `#` 字符）。每个小节都会由模版自动给出标题。
|
||||
- 在 `overview` 节中，用一个段落为整个任务主体设定语境；
|
||||
- 在 `prerequisites` 节中，尽可能使用项目符号列表。
|
||||
额外的环境准备条件要加在 `include` 短代码之后。
|
||||
默认的环境准备条件是拥有一个在运行的 Kubernetes 集群。
|
||||
- 在 `steps` 节中，使用编号符号列表。
|
||||
- 在 `discussion` 节中，使用正常文字内容来对 `steps` 节中内容展开叙述。
|
||||
- 在 `whatsnext` 节中，使用项目符号列表（不超过 5 项），列举读者可能接下来有兴趣
|
||||
阅读的主题。
|
||||
|
||||
已上线的任务主题示例之一是[使用 HTTP 代理来访问 Kubernetes API](/zh/docs/tasks/extend-kubernetes/http-proxy-access-api/)。
|
||||
|
||||
<!--
|
||||
### Tutorial
|
||||
|
||||
A tutorial page shows how to accomplish a goal that is larger than a single
|
||||
task. Typically a tutorial page has several sections, each of which has a
|
||||
sequence of steps. For example, a tutorial might provide a walkthrough of a
|
||||
code sample that illustrates a certain feature of Kubernetes. Tutorials can
|
||||
include surface-level explanations, but should link to related concept topics
|
||||
for deep explanations.
|
||||
|
||||
To write a new tutorial page, create a Markdown file in a subdirectory of the
|
||||
`/content/en/docs/tutorials` directory, with the following characteristics:
|
||||
|
||||
| Page section |
|
||||
|----------------|
|
||||
| overview |
|
||||
| prerequisites |
|
||||
| objectives |
|
||||
| lessoncontent |
|
||||
| cleanup |
|
||||
| whatsnext |
|
||||
-->
|
||||
### 教程（Tutorial） {#tutorial}
|
||||
|
||||
教程页面描述如果完成一个比单一任务规模更大的目标。通常教程页面会有多个小节，
|
||||
每个小节由一系列步骤组成。例如，每个教程可能提供对代码示例的讲解，便于用户
|
||||
了解 Kubernetes 的某个功能特性。教程可以包含表面层面的概念解释，对于更深层面
|
||||
的概念主题应该使用链接。
|
||||
|
||||
撰写新的教程页面时，在 `/content/en/docs/tutorials` 目录下面的子目录中创建新的
|
||||
Markdown 文件。该文件有以下特点。
|
||||
|
||||
| 页面节区 |
|
||||
|---------------------------|
|
||||
| overview （概述） |
|
||||
| prerequisites （环境准备）|
|
||||
| objectives （目标） |
|
||||
| lessoncontent （教程内容）|
|
||||
| cleanup （清理工作） |
|
||||
| whatsnext （接下来） |
|
||||
|
||||
<!--
|
||||
The `overview`, `objectives`, and `lessoncontent` sections appear as comments in the tutorial page.
|
||||
You can add the `prerequisites`, `cleanup`, and `whatsnext` sections to your page
|
||||
with the `heading` shortcode.
|
||||
|
||||
Within each section, write your content. Use the following guidelines:
|
||||
|
||||
- Use a minimum of H2 headings (with two leading `#` characters). The sections
|
||||
themselves are titled automatically by the template.
|
||||
- For `overview`, use a paragraph to set context for the entire topic.
|
||||
- For `prerequisites`, use bullet lists when possible. Add additional
|
||||
prerequisites below the ones included by default.
|
||||
- For `objectives`, use bullet lists.
|
||||
- For `lessoncontent`, use a mix of numbered lists and narrative content as
|
||||
appropriate.
|
||||
- For `cleanup`, use numbered lists to describe the steps to clean up the
|
||||
state of the cluster after finishing the task.
|
||||
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
|
||||
interested in reading next.
|
||||
|
||||
An example of a published tutorial topic is
|
||||
[Running a Stateless Application Using a Deployment](/docs/tutorials/stateless-application/run-stateless-application-deployment/).
|
||||
-->
|
||||
教程页面的 `overview`、`objectives` 和 `lessoncontent` 小节显示为注释形式。
|
||||
你可以使用 `heading` 短代码根据需要添加 `prerequisites`、`cleanup` 和
|
||||
`whatsnext` 小节。
|
||||
|
||||
在每个小节中编写内容时，请注意以下规定：
|
||||
|
||||
- 最低使用二级标题（H2，标题前面有两个 `#` 字符）。模版会自动为每个小节设置标题。
|
||||
- 在 `overview` 节中，用一个段落为整个主题设定语境；
|
||||
- 在 `prerequisites` 节中，尽可能使用项目符号列表。
|
||||
额外的环境准备条件要加在已包含的条件之后。
|
||||
- 在 `objectives` 节中，使用项目符号列表。
|
||||
- 在 `lessoncontent` 节中，结合使用编号符号列表和叙述性文字。
|
||||
- 在 `cleanup` 节中，使用编号符号列表来描述任务结束后清理集群状态所需要的步骤。
|
||||
- 在 `whatsnext` 节中，使用项目符号列表（不超过 5 项），列举读者可能接下来有兴趣
|
||||
阅读的主题。
|
||||
|
||||
已发布的教程主题的一个例子是
|
||||
[使用 Deployment 运行无状态应用](/zh/docs/tutorials/stateless-application/run-stateless-application-deployment/).
|
||||
|
||||
<!--
|
||||
### Reference
|
||||
|
||||
A component tool reference page shows the description and flag options output for
|
||||
a Kubernetes component tool. Each page generates from scripts using the component tool commands.
|
||||
|
||||
A tool reference page has several possible sections:
|
||||
|
||||
| Page section |
|
||||
|--------------------------------|
|
||||
| synopsis |
|
||||
| options |
|
||||
| options from parent commands |
|
||||
| examples |
|
||||
| seealso |
|
||||
|
||||
Examples of published tool reference pages are:
|
||||
|
||||
- [kubeadm init](/docs/reference/setup-tools/kubeadm/kubeadm-init/)
|
||||
- [kube-apiserver](/docs/reference/command-line-tools-reference/kube-apiserver/)
|
||||
- [kubectl](/docs/reference/kubectl/kubectl/)
|
||||
-->
|
||||
### 参考（Reference） {#reference}
|
||||
|
||||
组件工具的参考页面给出的是某个 Kubernetes 组件工具的描述和参数选项输出。
|
||||
每个页面都是使用组件工具命令基于脚本生成的。
|
||||
|
||||
每个工具参考页面可能包含以下小节：
|
||||
|
||||
| 页面小节 |
|
||||
|-----------------|
|
||||
| synopsis (用法）|
|
||||
| options（选项） |
|
||||
| options from parent commands (从父命令集成的选项） |
|
||||
| examples （示例）|
|
||||
| seealso （参考）|
|
||||
|
||||
已发布的工具参考页面示例包括：
|
||||
|
||||
- [kubeadm init](/zh/docs/reference/setup-tools/kubeadm/kubeadm-init/)
|
||||
- [kube-apiserver](/zh/docs/reference/command-line-tools-reference/kube-apiserver/)
|
||||
- [kubectl](/zh/docs/reference/kubectl/kubectl/)
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
<!--
|
||||
- Learn about the [Style guide](/docs/contribute/style/style-guide/)
|
||||
- Learn about the [Content guide](/docs/contribute/style/content-guide/)
|
||||
- Learn about [content organization](/docs/contribute/style/content-organization/)
|
||||
-->
|
||||
- 了解[样式指南](/zh/docs/contribute/style/style-guide/)
|
||||
- 了解[内容指南](/zh/docs/contribute/style/content-guide/)
|
||||
- 了解[内容组织](/zh/docs/contribute/style/content-organization/)
|
||||
|
||||
|
|
@ -1,353 +0,0 @@
|
|||
---
|
||||
title: 使用页面模板
|
||||
content_type: concept
|
||||
weight: 30
|
||||
---
|
||||
|
||||
<!--
|
||||
---
|
||||
title: Using Page Templates
|
||||
content_type: concept
|
||||
weight: 30
|
||||
---
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
<!--
|
||||
When contributing new topics, apply one of the following templates to them.
|
||||
This standardizes the user experience of a given page.
|
||||
-->
|
||||
|
||||
当贡献新主题时，选择下列模板中的一种。
|
||||
这使指定页面的用户体验标准化。
|
||||
|
||||
<!--
|
||||
The page templates are in the
|
||||
[`layouts/partials/templates`](https://git.k8s.io/website/layouts/partials/templates)
|
||||
directory of the [`kubernetes/website`](https://github.com/kubernetes/website)
|
||||
repository.
|
||||
-->
|
||||
|
||||
页面模板在 [`kubernetes/website`](https://github.com/kubernetes/website) 仓库的 [`layouts/partials/templates`](https://git.k8s.io/website/layouts/partials/templates) 目录中。
|
||||
|
||||
{{< note >}}
|
||||
<!--
|
||||
Every new topic needs to use a template. If you are unsure which
|
||||
template to use for a new topic, start with the
|
||||
[concept template](#concept-template).
|
||||
-->
|
||||
|
||||
每个新主题都需要使用模板。如果你不确定新主题要使用哪个模板，请从[概念模板](#概念模板)开始。
|
||||
{{< /note >}}
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<!-- body -->
|
||||
|
||||
<!--
|
||||
## Concept template
|
||||
-->
|
||||
|
||||
## 概念模板
|
||||
|
||||
<!--
|
||||
A concept page explains some aspect of Kubernetes. For example, a concept
|
||||
page might describe the Kubernetes Deployment object and explain the role it
|
||||
plays as an application once it is deployed, scaled, and updated. Typically, concept
|
||||
pages don't include sequences of steps, but instead provide links to tasks or
|
||||
tutorials.
|
||||
-->
|
||||
|
||||
每个概念页面负责解释 Kubernetes 的某方面。例如，概念页面可以描述 Kubernetes Deployment 对象，并解释当部署、扩展和更新时，它作为应用程序所扮演的角色。一般来说，概念页面不包括步骤序列，而是提供任务或教程的链接。
|
||||
|
||||
|
||||
<!--
|
||||
To write a new concept page, create a Markdown file in a subdirectory of the
|
||||
`/content/en/docs/concepts` directory, with the following characteristics:
|
||||
-->
|
||||
|
||||
要编写新的概念页面，请在 `/content/en/docs/concepts` 目录的子目录中创建一个 Markdown 文件，其特点如下：
|
||||
|
||||
<!--
|
||||
- In the page's YAML front-matter, set `content_type: concept`.
|
||||
- In the page's body, set the required `capture` variables and any optional
|
||||
ones you want to include:
|
||||
-->
|
||||
|
||||
- 在页面的 YAML 头部，设置 `content_type: concept`。
|
||||
- 在页面的 body 中，设置所需的 `capture` 变量和所有想要包含的变量：
|
||||
|
||||
| 变量 | 必需? |
|
||||
|---------------|-----------|
|
||||
| overview | 是 |
|
||||
| body | 是 |
|
||||
| whatsnext | 否 |
|
||||
|
||||
<!--
|
||||
The page's body will look like this (remove any optional captures you don't
|
||||
need):
|
||||
-->
|
||||
|
||||
页面的 body 看起来像这样（移除所有不想要的可选 `capture` 变量）：
|
||||
|
||||
```
|
||||
{{%/* capture overview */%}}
|
||||
|
||||
{{%/* /capture */%}}
|
||||
|
||||
{{%/* capture body */%}}
|
||||
|
||||
{{%/* /capture */%}}
|
||||
|
||||
{{%/* capture whatsnext */%}}
|
||||
|
||||
{{%/* /capture */%}}
|
||||
```
|
||||
|
||||
<!--
|
||||
- Within each section, write your content. Use the following guidelines:
|
||||
- Use a minimum of H2 headings (with two leading `#` characters). The sections
|
||||
themselves are titled automatically by the template.
|
||||
- For `overview`, use a paragraph to set context for the entire topic.
|
||||
- For `body`, explain the concept using free-form Markdown.
|
||||
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
|
||||
interested in reading next.
|
||||
-->
|
||||
|
||||
- 在每个章节中写下你的内容。请遵从以下规则：
|
||||
- 使用不低于 H2 级别的标题（避免使用 H1 的标题，但 H3、H4 的标题是可以的）（以两个 `#` 字符开头）。这些章节本身是由模板自动命名的。
|
||||
- 在 `overview` 节，用一个段落的篇幅来为当前话题设定语境。
|
||||
- 在 `body` 节，使用自由形式的 Markdown 文件来解释概念。
|
||||
- 在 `whatsnext` 节，列出读者接下来可能感兴趣的最多 5 个主题。
|
||||
|
||||
<!--
|
||||
An example of a published topic that uses the concept template is
|
||||
[Annotations](/docs/concepts/overview/working-with-objects/annotations/). The
|
||||
page you are currently reading also uses the concept template.
|
||||
-->
|
||||
|
||||
使用概念模板的已发布主题的一个示例是[注解](/docs/concepts/overview/working-with-objects/annotations/)。你当前正在阅读的页面也使用概念模板。
|
||||
|
||||
<!--
|
||||
## Task template
|
||||
-->
|
||||
|
||||
## 任务模板
|
||||
|
||||
<!--
|
||||
A task page shows how to do a single thing, typically by giving a short
|
||||
sequence of steps. Task pages have minimal explanation, but often provide links
|
||||
to conceptual topics that provide related background and knowledge.
|
||||
-->
|
||||
|
||||
任务页面展示了如何完成单个任务，通常是通过给出一个简短的步骤序列。任务页面中解释性质的文字极少，但是通常会给出提供相关背景和知识的概念主题的链接。
|
||||
|
||||
<!--
|
||||
To write a new task page, create a Markdown file in a subdirectory of the
|
||||
`/content/en/docs/tasks` directory, with the following characteristics:
|
||||
-->
|
||||
|
||||
要编写新的任务页面，请在 `/content/en/docs/tasks` 目录的子目录中创建一个 Markdown 文件，其特点如下：
|
||||
|
||||
<!--
|
||||
- In the page's YAML front-matter, set `content_type: task`.
|
||||
- In the page's body, set the required `capture` variables and any optional
|
||||
ones you want to include:
|
||||
-->
|
||||
|
||||
- 在页面的 YAML 头部，设置 `content_type: task`。
|
||||
- 在页面的 body 中，设置所需的 `capture` 变量和所有想要包含的变量：
|
||||
|
||||
| 变量 | 必需? |
|
||||
|---------------|-----------|
|
||||
| overview | 是 |
|
||||
| prerequisites | 是 |
|
||||
| steps | 否 |
|
||||
| discussion | 否 |
|
||||
| whatsnext | 否 |
|
||||
|
||||
<!--
|
||||
The page's body will look like this (remove any optional captures you don't
|
||||
need):
|
||||
-->
|
||||
|
||||
页面的 body 看起来像这样（移除所有不想要的可选 `capture` 变量）：
|
||||
|
||||
```
|
||||
{{%/* capture overview */%}}
|
||||
|
||||
{{%/* /capture */%}}
|
||||
|
||||
{{%/* capture prerequisites */%}}
|
||||
|
||||
{{</* include "task-tutorial-prereqs.md" */>}} {{</* version-check */>}}
|
||||
|
||||
{{%/* /capture */%}}
|
||||
|
||||
{{%/* capture steps */%}}
|
||||
|
||||
{{%/* /capture */%}}
|
||||
|
||||
{{%/* capture discussion */%}}
|
||||
|
||||
{{%/* /capture */%}}
|
||||
|
||||
{{%/* capture whatsnext */%}}
|
||||
|
||||
{{%/* /capture */%}}
|
||||
```
|
||||
|
||||
<!--
|
||||
- Within each section, write your content. Use the following guidelines:
|
||||
- Use a minimum of H2 headings (with two leading `#` characters). The sections
|
||||
themselves are titled automatically by the template.
|
||||
- For `overview`, use a paragraph to set context for the entire topic.
|
||||
- For `prerequisites`, use bullet lists when possible. Start adding additional
|
||||
prerequisites below the `include`. The default prerequisites include a running Kubernetes cluster.
|
||||
- For `steps`, use numbered lists.
|
||||
- For discussion, use normal content to expand upon the information covered
|
||||
in `steps`.
|
||||
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
|
||||
interested in reading next.
|
||||
-->
|
||||
|
||||
- 在每个章节中写下你的内容。请遵从以下规则：
|
||||
- 使用不低于 H2 级别的标题（避免使用 H1 的标题，但 H3、H4 的标题是可以的）（以两个 `#` 字符开头）。这些章节本身是由模板自动命名的。
|
||||
- 在 `overview` 节，用一个段落的篇幅来为当前话题设定语境。
|
||||
- 在 `prerequisites 节`，如果有可能，请使用列表。在 `include` 下开始添加额外的先决条件。默认的先决条件包括运行中的 Kubernetes 集群。
|
||||
- 在 `steps` 节，使用编号列表。
|
||||
- 在讨论部分，使用通常的内容来扩展 `steps` 中包含的信息。
|
||||
- 在 `whatsnext` 节，列出读者接下来可能感兴趣的最多 5 个主题。
|
||||
|
||||
<!--
|
||||
An example of a published topic that uses the task template is [Using an HTTP proxy to access the Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api).
|
||||
-->
|
||||
|
||||
使用任务模板的已发布主题的一个示例是[使用 HTTP 代理访问 Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api)。
|
||||
|
||||
<!--
|
||||
## Tutorial template
|
||||
-->
|
||||
|
||||
## 教程模板
|
||||
|
||||
<!--
|
||||
A tutorial page shows how to accomplish a goal that is larger than a single
|
||||
task. Typically a tutorial page has several sections, each of which has a
|
||||
sequence of steps. For example, a tutorial might provide a walkthrough of a
|
||||
code sample that illustrates a certain feature of Kubernetes. Tutorials can
|
||||
include surface-level explanations, but should link to related concept topics
|
||||
for deep explanations.
|
||||
-->
|
||||
|
||||
教程页面展示了如何完成比单个任务更大的目标。通常教程页有几个章节，每个章节都有步骤说明。例如，教程可以提供说明 Kubernetes 的特定特性的代码示例的演练。教程可以包括表层解释，但是应该链接到相关的概念主题以进行深入解释。
|
||||
|
||||
<!--
|
||||
To write a new tutorial page, create a Markdown file in a subdirectory of the
|
||||
`/content/en/docs/tutorials` directory, with the following characteristics:
|
||||
-->
|
||||
|
||||
要编写新的教程页面，请在 `/content/en/docs/tutorials` 目录的子目录中创建一个 Markdown 文件，其特点如下：
|
||||
|
||||
<!--
|
||||
- In the page's YAML front-matter, set `content_type: tutorial`.
|
||||
- In the page's body, set the required `capture` variables and any optional
|
||||
ones you want to include:
|
||||
-->
|
||||
|
||||
- 在页面的 YAML 头部，设置 `content_type: tutorial`。
|
||||
- 在页面的 body 中，设置所需的 `capture` 变量和所有想要包含的变量：
|
||||
|
||||
| 变量 | 必需? |
|
||||
|---------------|-----------|
|
||||
| overview | 是 |
|
||||
| prerequisites | 是 |
|
||||
| objectives | 是 |
|
||||
| lessoncontent | 是 |
|
||||
| cleanup | 否 |
|
||||
| whatsnext | 否 |
|
||||
|
||||
<!--
|
||||
The page's body will look like this (remove any optional captures you don't
|
||||
need):
|
||||
-->
|
||||
|
||||
页面的 body 看起来像这样（移除所有不想要的可选 `capture` 变量）：
|
||||
|
||||
```
|
||||
{{%/* capture overview */%}}
|
||||
|
||||
{{%/* /capture */%}}
|
||||
|
||||
{{%/* capture prerequisites */%}}
|
||||
|
||||
{{</* include "task-tutorial-prereqs.md" */>}} {{</* version-check */>}}
|
||||
|
||||
{{%/* /capture */%}}
|
||||
|
||||
{{%/* capture objectives */%}}
|
||||
|
||||
{{%/* /capture */%}}
|
||||
|
||||
{{%/* capture lessoncontent */%}}
|
||||
|
||||
{{%/* /capture */%}}
|
||||
|
||||
{{%/* capture cleanup */%}}
|
||||
|
||||
{{%/* /capture */%}}
|
||||
|
||||
{{%/* capture whatsnext */%}}
|
||||
|
||||
{{%/* /capture */%}}
|
||||
```
|
||||
|
||||
<!--
|
||||
- Within each section, write your content. Use the following guidelines:
|
||||
- Use a minimum of H2 headings (with two leading `#` characters). The sections
|
||||
themselves are titled automatically by the template.
|
||||
- For `overview`, use a paragraph to set context for the entire topic.
|
||||
- For `prerequisites`, use bullet lists when possible. Add additional
|
||||
prerequisites below the ones included by default.
|
||||
- For `objectives`, use bullet lists.
|
||||
- For `lessoncontent`, use a mix of numbered lists and narrative content as
|
||||
appropriate.
|
||||
- For `cleanup`, use numbered lists to describe the steps to clean up the
|
||||
state of the cluster after finishing the task.
|
||||
- For `whatsnext`, give a bullet list of up to 5 topics the reader might be
|
||||
interested in reading next.
|
||||
-->
|
||||
|
||||
- 在每个章节中写下你的内容。请遵从以下规则：
|
||||
- 使用不低于 H2 级别的标题（避免使用 H1 的标题，但 H3、H4 的标题是可以的）（以两个 `#` 字符开头）。这些章节本身是由模板自动命名的。
|
||||
- 在 `overview` 节，用一个段落的篇幅来为当前话题设定语境。
|
||||
- 在 `prerequisites` 节，如果有可能，请使用列表。在默认情况下添加额外的先决条件。
|
||||
- 在 `objectives` 节，使用列表。
|
||||
- 在 `lessoncontent` 节，适当地使用编号列表和叙述内容的组合。
|
||||
- 在 `cleanup` 节，使用编号列表描述完成任务后清理集群状态的步骤。
|
||||
- 在 `whatsnext` 节，列出读者接下来可能感兴趣的最多 5 个主题。
|
||||
|
||||
<!--
|
||||
An example of a published topic that uses the tutorial template is
|
||||
[Running a Stateless Application Using a Deployment](/docs/tutorials/stateless-application/run-stateless-application-deployment/).
|
||||
-->
|
||||
|
||||
使用教程模板的已发布主题的一个示例是[使用部署运行无状态应用程序](/docs/tutorials/stateless-application/run-stateless-application-deployment/)。
|
||||
|
||||
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
|
||||
<!--
|
||||
- Learn about the [style guide](/docs/contribute/style/style-guide/)
|
||||
- Learn about [content organization](/docs/contribute/style/content-organization/)
|
||||
-->
|
||||
|
||||
- 学习[样式指南](/docs/contribute/style/style-guide/)
|
||||
- 学习[内容组织](/docs/contribute/style/content-organization/)
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -3,13 +3,10 @@ title: 撰写新主题
|
|||
content_type: task
|
||||
weight: 20
|
||||
---
|
||||
|
||||
<!--
|
||||
---
|
||||
title: Writing a new topic
|
||||
content_type: task
|
||||
weight: 20
|
||||
---
|
||||
-->
|
||||
|
||||
<!-- overview -->
|
||||
|
|
@ -18,30 +15,24 @@ This page shows how to create a new topic for the Kubernetes docs.
|
|||
-->
|
||||
本页面展示如何为 Kubernetes 文档库创建新主题。
|
||||
|
||||
|
||||
## {{% heading "prerequisites" %}}
|
||||
|
||||
<!--
|
||||
Create a fork of the Kubernetes documentation repository as described in
|
||||
[Start contributing](/docs/contribute/start/).
|
||||
-->
|
||||
|
||||
如[开始贡献](/docs/contribute/start/)中所述，创建 Kubernetes 文档库的分支。
|
||||
|
||||
如[发起 PR](/zh/docs/contribute/new-content/open-a-pr/)中所述，创建 Kubernetes 文档库的派生副本。
|
||||
|
||||
<!-- steps -->
|
||||
|
||||
<!--
|
||||
## Choosing a page type
|
||||
-->
|
||||
|
||||
## 选择页面类型
|
||||
|
||||
<!--
|
||||
As you prepare to write a new topic, think about the page type that would fit your content the best:
|
||||
-->
|
||||
## 选择页面类型
|
||||
|
||||
当你准备写一个新的主题时，考虑一下最适合你的内容的页面类型：
|
||||
当你准备编写一个新的主题时，考虑一下最适合你的内容的页面类型：
|
||||
|
||||
<!--
|
||||
Guidelines for choosing a page type
|
||||
|
|
@ -52,30 +43,25 @@ Task | A task page shows how to do a single thing. The idea is to give readers a
|
|||
Tutorial | A tutorial page shows how to accomplish a goal that ties together several Kubernetes features. A tutorial might provide several sequences of steps that readers can actually do as they read the page. Or it might provide explanations of related pieces of code. For example, a tutorial could provide a walkthrough of a code sample. A tutorial can include brief explanations of the Kubernetes features that are being tied together, but should link to related concept topics for deep explanations of individual features.
|
||||
-->
|
||||
|
||||
|
||||
{{< table caption = "选择页面类型的准则" >}}
|
||||
{{< table caption = "选择页面类型的说明" >}}
|
||||
类型 | 描述
|
||||
:--- | :----------
|
||||
概念 | 每个概念页面负责解释 Kubernetes 的某方面。例如，概念页面可以描述 Kubernetes Deployment 对象，并解释当部署、扩展和更新时，它作为应用程序所扮演的角色。一般来说，概念页面不包括步骤序列，而是提供任务或教程的链接。一个概念主题的示例，请参见 <a href="/docs/concepts/architecture/nodes/">节点</a>。
|
||||
任务 | 任务页面展示了如何完成单个任务。这样做的目的是给读者提供一系列的步骤，让他们在阅读时可以实际执行。任务页面可长可短，前提是它始终围绕着某个主题。在任务页面中，可以将简短的解释与要执行的步骤混合在一起。如果需要提供较长的解释，则应在概念主题中进行。相关联的任务和概念主题应该相互链接。一个简短的任务页面的实例，请参见 <a href="/docs/tasks/configure-pod-container/configure-volume-storage/">配置一个使用卷进行存储的 Pod</a>。一个较长的任务页面的实例，请参见 <a href="/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/">配置活动性和就绪性探针</a>。
|
||||
教程 | 教程页面展示如何实现某个目标，该目标将几个 Kubernetes 特性联系在一起。教程可能提供一些步骤序列，读者可以在阅读页面时实际执行这些步骤。或者它可以提供相关代码片段的解释。例如，教程可以提供代码示例的讲解。教程可以包括对 Kubernetes 几个关联特性的简要解释，但应该链接到相关概念主题，以便深入解释各个特性。
|
||||
概念（Concept） | 概念页面负责解释 Kubernetes 的某方面。例如，概念页面可以描述 Kubernetes Deployment 对象，并解释当部署、扩展和更新时，它作为应用程序所扮演的角色。一般来说，概念页面不包括步骤序列，而是提供任务或教程的链接。概念主题的示例可参见 <a href="/zh/docs/concepts/architecture/nodes/">节点</a>。
|
||||
任务（Task） | 任务页面展示如何完成特定任务。其目的是给读者提供一系列的步骤，让他们在阅读时可以实际执行。任务页面可长可短，前提是它始终围绕着某个主题展开。在任务页面中，可以将简短的解释与要执行的步骤混合在一起。如果需要提供较长的解释，则应在概念主题中进行。相关联的任务和概念主题应该相互链接。一个简短的任务页面的实例可参见 <a href="/zh/docs/tasks/configure-pod-container/configure-volume-storage/">配置 Pod 使用卷存储</a>。一个较长的任务页面的实例可参见 <a href="/zh/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/">配置活跃性和就绪性探针</a>。
|
||||
教程（Tutorial） | 教程页面展示如何实现某个目标，该目标将若干 Kubernetes 功能特性联系在一起。教程可能提供一些步骤序列，读者可以在阅读页面时实际执行这些步骤。或者它可以提供相关代码片段的解释。例如，教程可以提供代码示例的讲解。教程可以包括对 Kubernetes 几个关联特性的简要解释，但有关更深入的特性解释应该链接到相关概念主题。
|
||||
{{< /table >}}
|
||||
|
||||
<!--
|
||||
Use a template for each new page. Each page type has a
|
||||
[template](/docs/contribute/style/page-templates/)
|
||||
that you can use as you write your topic. Using templates helps ensure
|
||||
Use a [content type](/docs/contribute/style/page-content-types/) for each new page
|
||||
that you write. Using page type helps ensure
|
||||
consistency among topics of a given type.
|
||||
-->
|
||||
为每个新页面使用模板。每种页面类型都有一个[模板](/docs/contribute/style/page-templates/)，这个模板可以在编写主题时使用。使用模板有助于确保给定类型主题之间的一致性。
|
||||
为每个新页面选择其[内容类型](/zh/docs/contribute/style/page-content-types/)。
|
||||
使用页面类型有助于确保给定类型的各主题之间保持一致。
|
||||
|
||||
<!--
|
||||
## Choosing a title and filename
|
||||
-->
|
||||
|
||||
## 选择标题和文件名
|
||||
|
||||
<!--
|
||||
Choose a title that has the keywords you want search engines to find.
|
||||
Create a filename that uses the words in your title separated by hyphens.
|
||||
For example, the topic with title
|
||||
|
|
@ -84,45 +70,47 @@ has filename `http-proxy-access-api.md`. You don't need to put
|
|||
"kubernetes" in the filename, because "kubernetes" is already in the
|
||||
URL for the topic, for example:
|
||||
-->
|
||||
## 选择标题和文件名
|
||||
|
||||
选择一个标题，标题中包含了要通过搜索引擎要查找的关键字。创建一个文件名，使用标题中由连字符分隔的单词。例如，标题为[使用 HTTP 代理访问 Kubernetes API](/docs/tasks/access-kubernetes-api/http-proxy-access-api/) 的主题的文件名为 `http-proxy-access-api.md`。你不需要在文件名中加上 "kubernetes"，因为 "kubernetes" 已经在主题的 URL 中了，例如：
|
||||
选择一个标题，确保其中包含希望搜索引擎发现的关键字。
|
||||
确定文件名时请使用标题中的单词，由连字符分隔。
|
||||
例如，标题为[Using an HTTP Proxy to Access Kubernetes API](/zh/docs/tasks/extend-kubernetes/http-proxy-access-api/)
|
||||
的主题的文件名为 `http-proxy-access-api.md`。
|
||||
你不需要在文件名中加上 "kubernetes"，因为 "kubernetes" 已经在主题的 URL 中了，
|
||||
例如：
|
||||
|
||||
/docs/tasks/access-kubernetes-api/http-proxy-access-api/
|
||||
/docs/tasks/extend-kubernetes/http-proxy-access-api/
|
||||
|
||||
<!--
|
||||
## Adding the topic title to the front matter
|
||||
-->
|
||||
|
||||
## 在页面头部添加主题标题
|
||||
|
||||
<!--
|
||||
In your topic, put a `title` field in the
|
||||
[front matter](https://gohugo.io/content-management/front-matter/).
|
||||
The front matter is the YAML block that is between the
|
||||
triple-dashed lines at the top of the page. Here's an example:
|
||||
|
||||
```
|
||||
title: Using an HTTP Proxy to Access the Kubernetes API
|
||||
```
|
||||
-->
|
||||
## 在页面前言中添加主题标题
|
||||
|
||||
在你的主题中，在[页面头部](https://gohugo.io/content-management/front-matter/)设置一个 `title` 字段。页面头部是位于页面顶部三条虚线之间的 YAML 块。下面是一个例子：
|
||||
在你的主题中，在[前言（front-matter）](https://gohugo.io/content-management/front-matter/)
|
||||
中设置一个 `title` 字段。
|
||||
前言是位于页面顶部三条虚线之间的 YAML 块。下面是一个例子：
|
||||
|
||||
<!--
|
||||
---
|
||||
title: Using an HTTP Proxy to Access the Kubernetes API
|
||||
---
|
||||
-->
|
||||
|
||||
---
|
||||
title: 使用 HTTP 代理访问 Kubernetes API
|
||||
---
|
||||
```
|
||||
---
|
||||
title: 使用 HTTP 代理访问 Kubernetes API
|
||||
---
|
||||
```
|
||||
|
||||
<!--
|
||||
## Choosing a directory
|
||||
-->
|
||||
|
||||
## 选择目录
|
||||
|
||||
<!--
|
||||
Depending on your page type, put your new file in a subdirectory of one of these:
|
||||
-->
|
||||
## 选择目录
|
||||
|
||||
根据页面类型，将新文件放入其中一个子目录中：
|
||||
|
||||
|
|
@ -134,31 +122,29 @@ Depending on your page type, put your new file in a subdirectory of one of these
|
|||
You can put your file in an existing subdirectory, or you can create a new
|
||||
subdirectory.
|
||||
-->
|
||||
|
||||
你可以将文件放在现有的子目录中，也可以创建一个新的子目录。
|
||||
|
||||
<!--
|
||||
## Placing your topic in the table of contents
|
||||
-->
|
||||
|
||||
## 将主题放在目录中
|
||||
|
||||
<!--
|
||||
The table of contents is built dynamically using the directory structure of the
|
||||
documentation source. The top-level directories under `/content/en/docs/` create
|
||||
top-level navigation, and subdirectories each have entries in the table of
|
||||
contents.
|
||||
-->
|
||||
## 将主题放在目录中
|
||||
|
||||
目录是使用文档源的目录结构动态构建的。`/content/en/docs/` 下的顶层目录创建顶层导航，它和子目录在目录中都有条目。
|
||||
目录是使用文档源的目录结构动态构建的。
|
||||
`/content/en/docs/` 下的顶层目录用于创建顶层导航条目，
|
||||
这些目录和它们的子目录在网站目录中都有对应条目。
|
||||
|
||||
<!--
|
||||
Each subdirectory has a file `_index.md`, which represents the "home" page for
|
||||
a given subdirectory's content. The `_index.md` does not need a template. It
|
||||
can contain overview content about the topics in the subdirectory.
|
||||
-->
|
||||
|
||||
每个子目录都有一个 `_index.md` 文件，它表示指定子目录内容的主页面。`_index.md` 文件不需要模板。它可以包含有关子目录中主题的概述内容。
|
||||
每个子目录都有一个 `_index.md` 文件，它表示的是该子目录内容的主页面。
|
||||
`_index.md` 文件不需要模板。它可以包含各子目录中主题的概述内容。
|
||||
|
||||
<!--
|
||||
Other files in a directory are sorted alphabetically by default. This is almost
|
||||
|
|
@ -167,22 +153,22 @@ subdirectory, set the `weight:` front-matter key to an integer. Typically, we
|
|||
use multiples of 10, to account for adding topics later. For instance, a topic
|
||||
with weight `10` will come before one with weight `20`.
|
||||
-->
|
||||
|
||||
默认情况下，目录中的其他文件按字母顺序排序。这几乎不是最好的顺序。要控制子目录中主题的相对排序，请将页面头部的键 `weight:` 设置为整数。通常我们使用 10 的倍数，添加后续主题时 `weight` 值递增。例如，`weight` 为 `10` 的主题将位于 `weight` 为 `20` 的主题之前。
|
||||
默认情况下，目录中的其他文件按字母顺序排序。这一般不是最好的顺序。
|
||||
要控制子目录中主题的相对排序，请将页面头部的键 `weight:` 设置为整数值。
|
||||
通常我们使用 10 的倍数，添加后续主题时 `weight` 值递增。
|
||||
例如，`weight` 为 `10` 的主题将位于 `weight` 为 `20` 的主题之前。
|
||||
|
||||
<!--
|
||||
## Embedding code in your topic
|
||||
-->
|
||||
|
||||
## 在主题中嵌入代码
|
||||
|
||||
<!--
|
||||
If you want to include some code in your topic, you can embed the code in your
|
||||
file directly using the markdown code block syntax. This is recommended for the
|
||||
following cases (not an exhaustive list):
|
||||
-->
|
||||
## 在主题中嵌入代码
|
||||
|
||||
如果你想在主题中嵌入一些代码，可以直接使用标记代码块语法将代码嵌入到文件中。建议用于以下情况（并非详尽列表）：
|
||||
如果你想在主题中嵌入一些代码，可以直接使用 Markdown 代码块语法将代码嵌入到文件中。
|
||||
建议在以下场合（并非详尽列表）使用嵌入代码：
|
||||
|
||||
<!--
|
||||
- The code shows the output from a command such as
|
||||
|
|
@ -202,34 +188,41 @@ following cases (not an exhaustive list):
|
|||
-->
|
||||
|
||||
- 代码显示来自命令的输出，例如 `kubectl get deploy mydeployment -o json | jq '.status'`。
|
||||
- 代码不够通用，用户无法验证。例如，你可以嵌入 YAML 文件来创建一个依赖于特定 [FlexVolume](/docs/concepts/storage/volumes#flexvolume)实现的 Pod。
|
||||
- 该代码是一个不完整的示例，因为它的目的是高亮显示大文件的部分内容。例如，在描述自定义 [PodSecurityPolicy](/docs/tasks/administer-cluster/sysctl-cluster/#podsecuritypolicy)的方法时，出于某些原因，你可以直接在主题文件中提供一个简短的片段。
|
||||
- 由于其他原因，该代码不适合用户验证。例如，当使用 `kubectl edit` 命令描述如何将新属性添加到资源时，你可以提供一个仅包含要添加的属性的简短示例。
|
||||
- 代码不够通用，用户无法验证。例如，你可以嵌入 YAML 文件来创建一个依赖于特定
|
||||
[FlexVolume](/zh/docs/concepts/storage/volumes#flexvolume) 实现的 Pod。
|
||||
- 该代码是一个不完整的示例，因为其目的是突出展现某个大文件中的部分内容。
|
||||
例如，在描述出于某些原因定制
|
||||
[PodSecurityPolicy](/zh/docs/tasks/administer-cluster/sysctl-cluster/#podsecuritypolicy)
|
||||
的方法时，你可以在主题文件中直接提供一个短的代码段。
|
||||
- 由于某些其他原因，该代码不适合用户验证。
|
||||
例如，当使用 `kubectl edit` 命令描述如何将新属性添加到资源时，
|
||||
你可以提供一个仅包含要添加的属性的简短示例。
|
||||
|
||||
<!--
|
||||
## Including code from another file
|
||||
-->
|
||||
|
||||
## 引用来自其他文件的代码
|
||||
|
||||
<!--
|
||||
Another way to include code in your topic is to create a new, complete sample
|
||||
file (or group of sample files) and then reference the sample from your topic.
|
||||
Use this method to include sample YAML files when the sample is generic and
|
||||
reusable, and you want the reader to try it out themselves.
|
||||
-->
|
||||
## 引用来自其他文件的代码
|
||||
|
||||
在主题中引用代码的另一种方法是创建一个新的、完整的示例文件（或示例文件组），然后从主题中引用这些示例。当示例是通用的和可重用的，并且你希望读者自己验证时，使用此方法引用示例 YAML 文件。
|
||||
在主题中引用代码的另一种方法是创建一个新的、完整的示例文件（或文件组），
|
||||
然后在主题中引用这些示例。当示例是通用的和可重用的，并且你希望读者自己验证时，
|
||||
使用此方法引用示例 YAML 文件。
|
||||
|
||||
<!--
|
||||
When adding a new standalone sample file, such as a YAML file, place the code in
|
||||
one of the `<LANG>/examples/` subdirectories where `<LANG>` is the language for
|
||||
the topic. In your topic file, use the `codenew` shortcode:
|
||||
-->
|
||||
添加新的独立示例文件（如 YAML 文件）时，将代码放在 `<LANG>/examples/` 的某个子目录中，
|
||||
其中 `<LANG>` 是该主题的语言。在主题文件中使用 `codenew` 短代码：
|
||||
|
||||
添加新的独立示例文件（如 YAML 文件）时，将代码放在 `<LANG>/examples/` 的某个子目录中，其中 `<LANG>` 是该主题的语言。在主题文件中使用 `codenew` 短代码：
|
||||
|
||||
<pre>{{< codenew file="<RELPATH>/my-example-yaml>" >}}</pre>
|
||||
```none
|
||||
{{</* codenew file="<RELPATH>/my-example-yaml>" */>}}
|
||||
```
|
||||
|
||||
<!--
|
||||
where `<RELPATH>` is the path to the file to include, relative to the
|
||||
|
|
@ -237,7 +230,9 @@ where `<RELPATH>` is the path to the file to include, relative to the
|
|||
file located at `/content/en/examples/pods/storage/gce-volume.yaml`.
|
||||
-->
|
||||
|
||||
`<RELPATH>` 是要引用的文件的路径，相对于 `examples` 目录。以下 Hugo 短代码引用了位于 `/content/en/examples/pods/storage/gce-volume.yaml` 的 YAML 文件。
|
||||
`<RELPATH>` 是要引用的文件的路径，相对于 `examples` 目录。以下 Hugo
|
||||
短代码引用了位于 `/content/en/examples/pods/storage/gce-volume.yaml` 的 YAML
|
||||
文件。
|
||||
|
||||
```none
|
||||
{{</* codenew file="pods/storage/gce-volume.yaml" */>}}
|
||||
|
|
@ -249,26 +244,23 @@ from interpreting them, use C-style comments directly after the `<` and before
|
|||
the `>` characters. View the code for this page for an example.
|
||||
-->
|
||||
{{< note >}}
|
||||
要展示上述示例中的原始 Hugo 短代码并避免 Hugo 对其进行解释，请直接在 `<` 字符之后和 `>` 字符之前使用 C 样式注释。请查看此页面的代码。
|
||||
要展示上述示例中的原始 Hugo 短代码并避免 Hugo 对其进行解释，
|
||||
请直接在 `<` 字符之后和 `>` 字符之前使用 C 样式注释。请查看此页面的代码。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
## Showing how to create an API object from a configuration file
|
||||
-->
|
||||
|
||||
## 显示如何从配置文件创建 API 对象
|
||||
|
||||
<!--
|
||||
If you need to demonstrate how to create an API object based on a
|
||||
configuration file, place the configuration file in one of the subdirectories
|
||||
under `<LANG>/examples`.
|
||||
-->
|
||||
|
||||
如果需要演示如何基于配置文件创建 API 对象，请将配置文件放在 `<LANG>/examples` 下的某个子目录中。
|
||||
|
||||
<!--
|
||||
In your topic, show this command:
|
||||
-->
|
||||
## 显示如何从配置文件创建 API 对象
|
||||
|
||||
如果需要演示如何基于配置文件创建 API 对象，请将配置文件放在 `<LANG>/examples`
|
||||
下的某个子目录中。
|
||||
|
||||
在主题中展示以下命令：
|
||||
|
||||
|
|
@ -283,39 +275,33 @@ Travis CI for the Website automatically runs this test case when PRs are
|
|||
submitted to ensure all examples pass the tests.
|
||||
-->
|
||||
{{< note >}}
|
||||
将新的 YAML 文件添加到 `<LANG>/examples` 目录时，请确保该文件也在 `<LANG>/examples_test.go` 文件中被引用。当提交拉取请求时，网站的 Travis CI 会自动运行此测试用例，以确保所有示例都通过测试。
|
||||
将新的 YAML 文件添加到 `<LANG>/examples` 目录时，请确保该文件也在
|
||||
`<LANG>/examples_test.go` 文件中被引用。
|
||||
当提交拉取请求时，网站的 Travis CI 会自动运行此测试用例，以确保所有示例都通过测试。
|
||||
{{< /note >}}
|
||||
|
||||
<!--
|
||||
For an example of a topic that uses this technique, see
|
||||
[Running a Single-Instance Stateful Application](/docs/tutorials/stateful-application/run-stateful-application/).
|
||||
-->
|
||||
|
||||
有关使用此技术的主题的示例，请参见[运行单实例有状态的应用](/docs/tutorials/stateful-application/run-stateful-application/)。
|
||||
有关使用此技术的主题的示例，请参见
|
||||
[运行单实例有状态的应用](/zh/docs/tutorials/stateful-application/run-stateful-application/)。
|
||||
|
||||
<!--
|
||||
## Adding images to a topic
|
||||
|
||||
Put image files in the `/images` directory. The preferred image format is SVG.
|
||||
-->
|
||||
## 向主题添加图片
|
||||
|
||||
## 向主题添加镜像
|
||||
将图片文件放入 `/images` 目录。首选的图片格式是 SVG。
|
||||
|
||||
<!--
|
||||
Put image files in the `/images` directory. The preferred
|
||||
image format is SVG.
|
||||
-->
|
||||
|
||||
将镜像文件放入 `/images` 目录。首选的镜像格式是 SVG。
|
||||
|
||||
|
||||
|
||||
<!--
|
||||
* Learn about [using page templates](/docs/home/contribute/page-templates/).
|
||||
* Learn about [staging your changes](/docs/home/contribute/stage-documentation-changes/).
|
||||
* Learn about [creating a pull request](/docs/home/contribute/create-pull-request/).
|
||||
-->
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* 学习[使用页面模板](/docs/home/contribute/page-templates/)。
|
||||
* 学习[展示你的修改](/docs/home/contribute/stage-documentation-changes/)。
|
||||
* 学习[创建一个拉取请求](/docs/home/contribute/create-pull-request/)。
|
||||
<!--
|
||||
* Learn about [using page content types](/docs/contribute/style/page-content-types/).
|
||||
* Learn about [creating a pull request](/docs/contribute/new-content/open-a-pr/).
|
||||
-->
|
||||
* 了解[使用页面内容类型](/zh/docs/contribute/style/page-content-types/).
|
||||
* 了解[创建 PR](/zh/docs/contribute/new-content/open-a-pr/).
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue