From c5641f18a122b01c1d205dca310864fba60a0f73 Mon Sep 17 00:00:00 2001 From: "xin.li" Date: Sun, 21 Jan 2024 21:36:03 +0800 Subject: [PATCH] [zh-cn] sync contribute/style/* Signed-off-by: xin.li --- .../docs/contribute/style/diagram-guide.md | 42 +++++++-------- .../contribute/style/hugo-shortcodes/index.md | 54 ++++++++++++++----- .../docs/contribute/style/write-new-topic.md | 6 +-- 3 files changed, 65 insertions(+), 37 deletions(-) diff --git a/content/zh-cn/docs/contribute/style/diagram-guide.md b/content/zh-cn/docs/contribute/style/diagram-guide.md index 799532882b..3e826dbca5 100644 --- a/content/zh-cn/docs/contribute/style/diagram-guide.md +++ b/content/zh-cn/docs/contribute/style/diagram-guide.md @@ -38,7 +38,7 @@ flowchart LR subgraph m[Mermaid.js] direction TB S[ ]-.- -C[使用 markdown 来
构造图表] --> +C[使用 Markdown 来
构造图表] --> D[在线
编辑器] end A[为什么图表
很有用] --> m @@ -120,11 +120,11 @@ The user benefits include: * __Better retention__. For some, it is easier to recall pictures rather than text. --> 用户获得的好处有： -* __较为友好的初次体验__：非常详尽的、只包含文本的欢迎页面对用户而言是蛮恐怖的， +* **较为友好的初次体验**：非常详尽的、只包含文本的欢迎页面对用户而言是蛮恐怖的， 尤其是初次接触 Kubernetes 的用户。 -* __快速理解概念__：图表可以帮助用户理解复杂主题下的要点。 +* **快速理解概念**：图表可以帮助用户理解复杂主题下的要点。 你的图表可以作为一种可视化的学习指南，将用户带入主题的细节。 -* __便于记忆__：对某些人而言，图形（图像）要比文字更容易记忆。 +* **便于记忆**：对某些人而言，图形（图像）要比文字更容易记忆。 对贡献者而言的好处有： -* __帮助确立所贡献文档的结构和内容__。例如， +* **帮助确立所贡献文档的结构和内容**。例如， 你可以先提供一个覆盖所有顶层要点的图表，然后再逐步展开细节。 -* __培养用户社区并提升其能力__。容易理解的文档，附以图表，能够吸引新的用户， +* **培养用户社区并提升其能力**。容易理解的文档，附以图表，能够吸引新的用户， 尤其是那些因为预见到复杂性而不愿参与的用户。 即使你的工作环境中不支持，你仍然可以使用 Mermaid 来创建、编辑图表。 -这种方法称作 __Mermaid+SVG__，在后文详细解释。 +这种方法称作 **Mermaid+SVG**，在后文详细解释。 {{< /note >}} -图 5. 外部工具方法步骤. +图 5. 外部工具方法步骤 @@ -1108,12 +1107,12 @@ The following lists several items to consider when adding diagram captions: * 使用 `{{}}` 短代码来为 Mermaid+SVG 和外部工具方法制作的图表添加标题。 * 对于内嵌方法制作的图表，使用简单的 Markdown 文本来为其添加标题。 -* 在你的图表标题前面添加 `图 <编号>.`. 你必须使用 `图` 字样， +* 在你的图表标题前面添加 `图 <编号>.`。你必须使用 `图` 字样， 并且编号必须对于文档页面中所有图表而言唯一。 在编号之后添加一个英文句号。 * 将图表标题添加到 `图 <编号>.` 之后，并且在同一行。 你必须为图表标题添加英文句点作为其结束标志。尽量保持标题文字简短。 -* 图表标题要放在图表 __之后__。 +* 图表标题要放在图表**之后**。 * 查看本页的源代码，`diagram-guide.md` 文件，可以将其作为示例。 -* 查阅 [Mermaid docs](https://mermaid-js.github.io/mermaid/#/) 以获得更多的解释和示例。 +* 查阅 [Mermaid 文档](https://mermaid-js.github.io/mermaid/#/)以获得更多的解释和示例。 -最重要的一点，__保持图表简单__。 +最重要的一点，**保持图表简单**。 这样做会节省你和其他贡献者的时间，同时也会方便新的以及有经验的用户阅读。 - diff --git a/content/zh-cn/docs/contribute/style/hugo-shortcodes/index.md b/content/zh-cn/docs/contribute/style/hugo-shortcodes/index.md index 82b0e305d7..65a67750c6 100644 --- a/content/zh-cn/docs/contribute/style/hugo-shortcodes/index.md +++ b/content/zh-cn/docs/contribute/style/hugo-shortcodes/index.md @@ -19,7 +19,8 @@ This page explains the custom Hugo shortcodes that can be used in Kubernetes Mar -关于短代码的更多信息可参见 [Hugo 文档](https://gohugo.io/content-management/shortcodes)。 +关于短代码的更多信息可参见 +[Hugo 文档](https://gohugo.io/content-management/shortcodes)。 @@ -86,6 +87,37 @@ Renders to: {{< feature-state for_k8s_version="v1.10" state="beta" >}} + +## 特性门控介绍 + +在此站点上的 Markdown 页面（`.md` 文件）中，你可以添加短代码来显示短代码的描述。 + + +### 特性门控 Demo 演示 + +下面是特性状态片段的 Demo，它显示该特性在最新的 Kubernetes 版本中处于稳定状态。 + +``` +{{}} +``` + + +渲染到： + +{{< feature-gate-description name="DryRun" >}} + 本语句中 `page` 参数的内容是 API 参考页面的 URL 后缀。 - -你可以通过指定 `text` 参数来更改链接的文本，例如通过链接到页面的 -{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="环境变量">}} -部分： +你可以通过指定 `text` 参数来更改链接的文本， +例如通过链接到页面的{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="环境变量">}}部分： ``` {{}} ``` - -如果你查看表格的 HTML 输出结果，你会看到 `` 元素 -后面紧接着下面的元素： +如果你查看表格的 HTML 输出结果，你会看到 `
` +元素后面紧接着下面的元素： ```html @@ -390,7 +419,7 @@ println "This is tab 2." ```go-html-template {{}} {{% tab name="Markdown" %}} -这是 **一些 markdown。** +这是**一些 markdown。** {{< note >}} 它甚至可以包含短代码。 {{< /note >}} @@ -411,7 +440,7 @@ Renders to: {{< tabs name="tab_with_md" >}} {{% tab name="Markdown" %}} -这是 **一些 markdown。** +这是**一些 markdown。** {{< note >}} 它甚至可以包含短代码。 {{< /note >}} @@ -493,7 +522,7 @@ the page. In the markdown of your page, use the `code` shortcode: --> 添加新的示例文件（例如 YAML 文件）时，在 `/examples/` 子目录之一中创建该文件，其中 `` 是页面的语言。 -在你的页面的 markdown 文本中，使用 `code` 短代码： +在你的页面的 Markdown 文本中，使用 `code` 短代码： ```none {{%/* code_sample file="/example-yaml>" */%}} @@ -661,7 +690,8 @@ Renders to: --> ### `{{}}` -`{{}}` 短代码可以生成站点参数 `latest` 不含前缀 `v` 的版本号取值。 +`{{}}` 短代码可以生成站点参数 `latest` 不含前缀 +`v` 的版本号取值。 转换为： diff --git a/content/zh-cn/docs/contribute/style/write-new-topic.md b/content/zh-cn/docs/contribute/style/write-new-topic.md index 93afbd430a..9fb7b776ff 100644 --- a/content/zh-cn/docs/contribute/style/write-new-topic.md +++ b/content/zh-cn/docs/contribute/style/write-new-topic.md @@ -84,7 +84,7 @@ URL for the topic, for example: 选择一个标题，确保其中包含希望搜索引擎发现的关键字。 确定文件名时请使用标题中的单词，由连字符分隔。 -例如，标题为[Using an HTTP Proxy to Access Kubernetes API](/zh-cn/docs/tasks/extend-kubernetes/http-proxy-access-api/) +例如，标题为[使用 HTTP 代理访问 Kubernetes API](/zh-cn/docs/tasks/extend-kubernetes/http-proxy-access-api/) 的主题的文件名为 `http-proxy-access-api.md`。 你不需要在文件名中加上 "kubernetes"，因为 "kubernetes" 已经在主题的 URL 中了， 例如： @@ -186,7 +186,7 @@ following cases (not an exhaustive list): - The code is not generic enough for users to try out. As an example, you can embed the YAML file for creating a Pod which depends on a specific - [FlexVolume](/docs/concepts/storage/volumes#flexvolume) implementation. + [FlexVolume](/docs/concepts/storage/volumes/#flexvolume) implementation. - The code is an incomplete example because its purpose is to highlight a portion of a larger file. For example, when describing ways to customize a [RoleBinding](/docs/reference/access-authn-authz/rbac/#role-binding-examples), @@ -199,7 +199,7 @@ following cases (not an exhaustive list): - 代码显示来自命令的输出，例如 `kubectl get deploy mydeployment -o json | jq '.status'`。 - 代码不够通用，用户无法验证。例如，你可以嵌入 YAML 文件来创建一个依赖于特定 - [FlexVolume](/zh-cn/docs/concepts/storage/volumes#flexvolume) 实现的 Pod。 + [FlexVolume](/zh-cn/docs/concepts/storage/volumes/#flexvolume) 实现的 Pod。 - 该代码是一个不完整的示例，因为其目的是突出展现某个大文件中的部分内容。 例如，在描述 [RoleBinding](/zh-cn/docs/reference/access-authn-authz/rbac/#role-binding-examples)
配置参数