diff --git a/content/zh/docs/contribute/style/write-new-topic.md b/content/zh/docs/contribute/style/write-new-topic.md index 82378bf1be8b8..bfe1ac919fc1f 100644 --- a/content/zh/docs/contribute/style/write-new-topic.md +++ b/content/zh/docs/contribute/style/write-new-topic.md @@ -16,7 +16,6 @@ weight: 20 - 本页面展示如何为 Kubernetes 文档库创建新主题。 {{% /capture %}} @@ -26,7 +25,7 @@ Create a fork of the Kubernetes documentation repository as described in [Start contributing](/docs/contribute/start/). --> -创建 Kubernetes 文档仓库的一个分支，如[开始贡献](/docs/contribute/start/)中所述。 +如[开始贡献](/docs/contribute/start/)中所述，创建 Kubernetes 文档库的分支。 {{% /capture %}} {{% capture steps %}} @@ -44,44 +43,22 @@ As you prepare to write a new topic, think about the page type that would fit yo 当你准备写一个新的主题时，考虑一下最适合你的内容的页面类型： - - - - - - - - - - - - - - - - -
概念每个概念页面负责解释 Kubernetes 的某方面。例如，概念页面可以描述 Kubernetes Deployment 对象，并解释当部署、扩展和更新时，它作为应用程序所扮演的角色。一般来说，概念页面不包括步骤序列，而是提供任务或教程的链接。一个概念主题的示例，请参见 节点.
任务任务页面展示了如何完成单个任务。这样做的目的是给读者一系列步骤，让他们在阅读时能够真正做到这一点。任务页面可长可短，前提是它始终聚焦在一个区域。在任务页面中，可以将简短的解释与要执行的步骤混合在一起，但如果需要提供冗长的解释，则应在概念主题中进行。相关联的任务和概念主题可以相互链接。一个简短的任务页面的实例，请参见 配置一个使用卷进行存储的 Pod. 一个较长的任务页面的实例，请参见 配置活动性和就绪性探测器
教程教程页面展示了如何实现将几个 Kubernetes 特性联系在一起的目标。教程可能提供一些步骤序列，读者可以在阅读页面时实际执行这些步骤。或者它可以提供相关代码片段的解释。例如，教程可以提供代码示例的演练。教程可以包括对 Kubernetes 几个关联特性的简要解释，但应该链接到相关概念主题，以便深入解释各个特性。
+{{< table caption = "选择页面类型的准则" >}} +类型 | 描述 +:--- | :---------- +概念 | 每个概念页面负责解释 Kubernetes 的某方面。例如，概念页面可以描述 Kubernetes Deployment 对象，并解释当部署、扩展和更新时，它作为应用程序所扮演的角色。一般来说，概念页面不包括步骤序列，而是提供任务或教程的链接。一个概念主题的示例，请参见 节点。 +任务 | 任务页面展示了如何完成单个任务。这样做的目的是给读者提供一系列的步骤，让他们在阅读时可以实际执行。任务页面可长可短，前提是它始终围绕着某个主题。在任务页面中，可以将简短的解释与要执行的步骤混合在一起。如果需要提供较长的解释，则应在概念主题中进行。相关联的任务和概念主题应该相互链接。一个简短的任务页面的实例，请参见 配置一个使用卷进行存储的 Pod。一个较长的任务页面的实例，请参见 配置活动性和就绪性探针。 +教程 | 教程页面展示如何实现某个目标，该目标将几个 Kubernetes 特性联系在一起。教程可能提供一些步骤序列，读者可以在阅读页面时实际执行这些步骤。或者它可以提供相关代码片段的解释。例如，教程可以提供代码示例的讲解。教程可以包括对 Kubernetes 几个关联特性的简要解释，但应该链接到相关概念主题，以便深入解释各个特性。 +{{< /table >}} - -为每个新页面使用模板。每种页面类型都有一个[模板](/docs/contribute/style/page-templates/)可以在编写主题时使用。使用模板有助于确保给定类型主题之间的一致性。 +为每个新页面使用模板。每种页面类型都有一个[模板](/docs/contribute/style/page-templates/)，这个模板可以在编写主题时使用。使用模板有助于确保给定类型主题之间的一致性。 -在你的主题中，在[页面头部](https://jekyllrb.com/docs/frontmatter/)设置一个 `title` 字段。页面头部是位于页面顶部三条虚线之间的 YAML 块。下面是一个例子： +在你的主题中，在[页面头部](https://gohugo.io/content-management/front-matter/)设置一个 `title` 字段。页面头部是位于页面顶部三条虚线之间的 YAML 块。下面是一个例子： -默认情况下，目录中的其他文件按字母顺序排序。这几乎不是最好的顺序。要控制子目录中主题的相对排序，请将页面头部的键 `weight:` 设置为整数。通常我们使用10的倍数，添加后续主题时权重值递增。例如，权重为 `10` 的主题将位于权重为 `20` 的主题之前。 +默认情况下，目录中的其他文件按字母顺序排序。这几乎不是最好的顺序。要控制子目录中主题的相对排序，请将页面头部的键 `weight:` 设置为整数。通常我们使用 10 的倍数，添加后续主题时 `weight` 值递增。例如，`weight` 为 `10` 的主题将位于 `weight` 为 `20` 的主题之前。 -如果你想在主题中包含一些代码，可以直接使用标记代码块语法将代码嵌入到文件中。建议用于以下情况（并非详尽列表）： +如果你想在主题中嵌入一些代码，可以直接使用标记代码块语法将代码嵌入到文件中。建议用于以下情况（并非详尽列表）： - 代码显示来自命令的输出，例如 `kubectl get deploy mydeployment -o json | jq '.status'`。 -- 代码不够通用，用户无法验证。例如，你可以嵌入 YAML 文件来创建一个依赖于特定 [Flexvolume](/docs/concepts/storage/volumes#flexvolume)实现的 Pod。 +- 代码不够通用，用户无法验证。例如，你可以嵌入 YAML 文件来创建一个依赖于特定 [FlexVolume](/docs/concepts/storage/volumes#flexvolume)实现的 Pod。 - 该代码是一个不完整的示例，因为它的目的是高亮显示大文件的部分内容。例如，在描述自定义 [PodSecurityPolicy](/docs/tasks/administer-cluster/sysctl-cluster/#podsecuritypolicy)的方法时，出于某些原因，你可以直接在主题文件中提供一个简短的片段。 - 由于其他原因，该代码不适合用户验证。例如，当使用 `kubectl edit` 命令描述如何将新属性添加到资源时，你可以提供一个仅包含要添加的属性的简短示例。 @@ -266,13 +242,12 @@ file located at `/content/en/examples/pods/storage/gce-volume.yaml`. {{}} ``` -{{< note >}} - +{{< note >}} 要展示上述示例中的原始 Hugo 短代码并避免 Hugo 对其进行解释，请直接在 `<` 字符之后和 `>` 字符之前使用 C 样式注释。请查看此页面的代码。 {{< /note >}} @@ -300,14 +275,13 @@ In your topic, show this command: kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml ``` -{{< note >}} - +{{< note >}} 将新的 YAML 文件添加到 `/examples` 目录时，请确保该文件也在 `/examples_test.go` 文件中被引用。当提交拉取请求时，网站的 Travis CI 会自动运行此测试用例，以确保所有示例都通过测试。 {{< /note >}} @@ -333,13 +307,12 @@ image format is SVG. {{% /capture %}} -{{% capture whatsnext %}} - +{{% capture whatsnext %}} * 学习[使用页面模板](/docs/home/contribute/page-templates/)。 * 学习[展示你的修改](/docs/home/contribute/stage-documentation-changes/)。 * 学习[创建一个拉取请求](/docs/home/contribute/create-pull-request/)。