From c5641f18a122b01c1d205dca310864fba60a0f73 Mon Sep 17 00:00:00 2001
From: "xin.li" <xin.li@daocloud.io>
Date: Sun, 21 Jan 2024 21:36:03 +0800
Subject: [PATCH] [zh-cn] sync contribute/style/*

Signed-off-by: xin.li <xin.li@daocloud.io>
---
 .../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 来<br>构造图表] -->
+C[使用 Markdown 来<br>构造图表] -->
 D[在线<br>编辑器]
 end
 A[为什么图表<br>很有用] --> m
@@ -120,11 +120,11 @@ The user benefits include:
 * __Better retention__. For some, it is easier to recall pictures rather than text.
 -->
 用户获得的好处有：
-* __较为友好的初次体验__：非常详尽的、只包含文本的欢迎页面对用户而言是蛮恐怖的，
+* **较为友好的初次体验**：非常详尽的、只包含文本的欢迎页面对用户而言是蛮恐怖的，
   尤其是初次接触 Kubernetes 的用户。
-* __快速理解概念__：图表可以帮助用户理解复杂主题下的要点。
+* **快速理解概念**：图表可以帮助用户理解复杂主题下的要点。
   你的图表可以作为一种可视化的学习指南，将用户带入主题的细节。
-* __便于记忆__：对某些人而言，图形（图像）要比文字更容易记忆。
+* **便于记忆**：对某些人而言，图形（图像）要比文字更容易记忆。
 
 <!--
 The contributor benefits include:
@@ -138,9 +138,9 @@ The contributor benefits include:
 -->
 对贡献者而言的好处有：
 
-* __帮助确立所贡献文档的结构和内容__。例如，
+* **帮助确立所贡献文档的结构和内容**。例如，
   你可以先提供一个覆盖所有顶层要点的图表，然后再逐步展开细节。
-* __培养用户社区并提升其能力__。容易理解的文档，附以图表，能够吸引新的用户，
+* **培养用户社区并提升其能力**。容易理解的文档，附以图表，能够吸引新的用户，
   尤其是那些因为预见到复杂性而不愿参与的用户。
 
 <!--
@@ -212,7 +212,7 @@ in your environment. This method is called __Mermaid+SVG__ and is explained
 below.
 -->
 即使你的工作环境中不支持，你仍然可以使用 Mermaid 来创建、编辑图表。
-这种方法称作 __Mermaid+SVG__，在后文详细解释。
+这种方法称作 **Mermaid+SVG**，在后文详细解释。
 {{< /note >}}
 
 <!--
@@ -585,7 +585,7 @@ method for adding `.svg` image files.
 图 5 给出使用外部工具来添加图表时所遵循的步骤。
 
 首先，要使用你的外部工具来创建图表，并将其保存为一个 `.svg` 文件或 `.png` 图片文件。
-之后，使用 __Mermaid+SVG__ 方法中相同的步骤添加 `.svg`（`.png`）文件。
+之后，使用 **Mermaid+SVG** 方法中相同的步骤添加 `.svg`（`.png`）文件。
 
 {{< mermaid >}}
 flowchart LR
@@ -622,7 +622,7 @@ click E "https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiZmxv
 <!--
 Figure 5. External Tool method steps
 -->
-图 5. 外部工具方法步骤.
+图 5. 外部工具方法步骤
 
 <!--
 The following lists the steps you should follow for adding a diagram using the External Tool method:
@@ -639,11 +639,11 @@ The following lists the steps you should follow for adding a diagram using the E
 使用外部工具方法来添加图表时，你要遵从的步骤如下：
 
 1. 使用你的外部工具来创建图表。
-1. 将图表的位置保存起来供其他贡献者访问。例如，你的工具可能提供一个指向图表的链接，
+2. 将图表的位置保存起来供其他贡献者访问。例如，你的工具可能提供一个指向图表的链接，
    或者你可以将源码文件（例如一个 `.xml` 文件）放置到一个公开的仓库，
    以便其他贡献者访问。
-1. 生成图表并将其下载为 `.svg` 或 `.png` 图片文件，保存到合适的 `../images/` 目录下。
-1. 使用 `{{</* figure */>}}` 短代码从 `.md` 文件中引用该图表。
+3. 生成图表并将其下载为 `.svg` 或 `.png` 图片文件，保存到合适的 `../images/` 目录下。
+4. 使用 `{{</* figure */>}}` 短代码从 `.md` 文件中引用该图表。
 5. 使用 `{{</* figure */>}}` 短代码的 `caption` 参数为图表设置标题。
 
 <!--
@@ -686,7 +686,7 @@ For more information on K8s and CNCF logos and images, check out
 关于 K8s 和 CNCF 商标与图片的详细信息，可参阅 [CNCF Artwork](https://github.com/cncf/artwork)。
 
 <!--
-The following lists advantages of the External Tool method: 
+The following lists advantages of the External Tool method:
 
 * Contributor familiarity with external tool.
 * Diagrams require more detail than what Mermaid can offer.
@@ -699,8 +699,8 @@ Don't forget to check that your diagram renders correctly using the
 * 贡献者对外部工具更为熟悉
 * 图表可能需要 Mermaid 所无法提供的细节
 
-不要忘记使用[本地](/zh-cn/docs/contribute/new-content/open-a-pr/#preview-locally)
-和 Netlify 预览来检查你的图表可以正常渲染。
+不要忘记使用[本地](/zh-cn/docs/contribute/new-content/open-a-pr/#preview-locally)和
+Netlify 预览来检查你的图表可以正常渲染。
 
 <!--
 ## Examples
@@ -866,7 +866,6 @@ K8s components to start a container.
 
 {{< figure src="/zh-cn/docs/images/diagram-guide-example-3.svg" alt="K8s system flow diagram" class="diagram-large" caption="图 8. K8s 系统流程图" link="https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb2RlIjoiJSV7aW5pdDp7XCJ0aGVtZVwiOlwibmV1dHJhbFwifX0lJVxuc2VxdWVuY2VEaWFncmFtXG4gICAgYWN0b3IgbWVcbiAgICBwYXJ0aWNpcGFudCBhcGlTcnYgYXMgY29udHJvbCBwbGFuZTxicj48YnI-YXBpLXNlcnZlclxuICAgIHBhcnRpY2lwYW50IGV0Y2QgYXMgY29udHJvbCBwbGFuZTxicj48YnI-ZXRjZCBkYXRhc3RvcmVcbiAgICBwYXJ0aWNpcGFudCBjbnRybE1nciBhcyBjb250cm9sIHBsYW5lPGJyPjxicj5jb250cm9sbGVyPGJyPm1hbmFnZXJcbiAgICBwYXJ0aWNpcGFudCBzY2hlZCBhcyBjb250cm9sIHBsYW5lPGJyPjxicj5zY2hlZHVsZXJcbiAgICBwYXJ0aWNpcGFudCBrdWJlbGV0IGFzIG5vZGU8YnI-PGJyPmt1YmVsZXRcbiAgICBwYXJ0aWNpcGFudCBjb250YWluZXIgYXMgbm9kZTxicj48YnI-Y29udGFpbmVyPGJyPnJ1bnRpbWVcbiAgICBtZS0-PmFwaVNydjogMS4ga3ViZWN0bCBjcmVhdGUgLWYgcG9kLnlhbWxcbiAgICBhcGlTcnYtLT4-ZXRjZDogMi4gc2F2ZSBuZXcgc3RhdGVcbiAgICBjbnRybE1nci0-PmFwaVNydjogMy4gY2hlY2sgZm9yIGNoYW5nZXNcbiAgICBzY2hlZC0-PmFwaVNydjogNC4gd2F0Y2ggZm9yIHVuYXNzaWduZWQgcG9kcyhzKVxuICAgIGFwaVNydi0-PnNjaGVkOiA1LiBub3RpZnkgYWJvdXQgcG9kIHcgbm9kZW5hbWU9XCIgXCJcbiAgICBzY2hlZC0-PmFwaVNydjogNi4gYXNzaWduIHBvZCB0byBub2RlXG4gICAgYXBpU3J2LS0-PmV0Y2Q6IDcuIHNhdmUgbmV3IHN0YXRlXG4gICAga3ViZWxldC0-PmFwaVNydjogOC4gbG9vayBmb3IgbmV3bHkgYXNzaWduZWQgcG9kKHMpXG4gICAgYXBpU3J2LT4-a3ViZWxldDogOS4gYmluZCBwb2QgdG8gbm9kZVxuICAgIGt1YmVsZXQtPj5jb250YWluZXI6IDEwLiBzdGFydCBjb250YWluZXJcbiAgICBrdWJlbGV0LT4-YXBpU3J2OiAxMS4gdXBkYXRlIHBvZCBzdGF0dXNcbiAgICBhcGlTcnYtLT4-ZXRjZDogMTIuIHNhdmUgbmV3IHN0YXRlIiwibWVybWFpZCI6IntcbiAgXCJ0aGVtZVwiOiBcImRlZmF1bHRcIlxufSIsInVwZGF0ZUVkaXRvciI6ZmFsc2UsImF1dG9TeW5jIjp0cnVlLCJ1cGRhdGVEaWFncmFtIjp0cnVlfQ" >}}
 
-
 <!--
 Code block:
 -->
@@ -1108,12 +1107,12 @@ The following lists several items to consider when adding diagram captions:
 
 * 使用 `{{</* figure */>}}` 短代码来为 Mermaid+SVG 和外部工具方法制作的图表添加标题。
 * 对于内嵌方法制作的图表，使用简单的 Markdown 文本来为其添加标题。
-* 在你的图表标题前面添加 `图 <编号>.`. 你必须使用 `图` 字样，
+* 在你的图表标题前面添加 `图 <编号>.`。你必须使用 `图` 字样，
   并且编号必须对于文档页面中所有图表而言唯一。
   在编号之后添加一个英文句号。
 * 将图表标题添加到 `图 <编号>.` 之后，并且在同一行。
   你必须为图表标题添加英文句点作为其结束标志。尽量保持标题文字简短。
-* 图表标题要放在图表 __之后__。
+* 图表标题要放在图表**之后**。
 
 <!--
 **Diagram Referral**
@@ -1248,7 +1247,7 @@ Here is the `{{</* figure */>}}` shortcode for this diagram:
 
 * Hugo Mermaid 短代码在在线编辑器中无法显示。
 
-* 如果你想要在在线编辑器中更改图表，你 __必须__ 保存它以便为图表生成新的 URL。
+* 如果想要在在线编辑器中更改图表，你**必须**保存它以便为图表生成新的 URL。
 
 * 点击本节中的图表，你可以查看其源代码及其在在线编辑器中的渲染效果。
 <!--
@@ -1259,13 +1258,12 @@ Here is the `{{</* figure */>}}` shortcode for this diagram:
 -->
 * 查看本页的源代码，`diagram-guide.md` 文件，可以将其作为示例。
 
-* 查阅 [Mermaid docs](https://mermaid-js.github.io/mermaid/#/) 以获得更多的解释和示例。
+* 查阅 [Mermaid 文档](https://mermaid-js.github.io/mermaid/#/)以获得更多的解释和示例。
 
 <!--
 Most important, __Keep Diagrams Simple__.
 This will save time for you and fellow contributors, and allow for easier reading
 by new and experienced users.
 -->
-最重要的一点，__保持图表简单__。
+最重要的一点，**保持图表简单**。
 这样做会节省你和其他贡献者的时间，同时也会方便新的以及有经验的用户阅读。
-
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
 <!--
 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 -->
 
@@ -86,6 +87,37 @@ Renders to:
 
 {{< feature-state for_k8s_version="v1.10" state="beta" >}}
 
+<!--
+## Feature gate description
+
+In a Markdown page (`.md` file) on this site, you can add a shortcode to
+display the description for a shortcode.
+-->
+## 特性门控介绍
+
+在此站点上的 Markdown 页面（`.md` 文件）中，你可以添加短代码来显示短代码的描述。
+
+<!--
+### Feature gate description demo
+
+Below is a demo of the feature state snippet, which displays the feature as
+stable in the latest Kubernetes version.
+-->
+### 特性门控 Demo 演示
+
+下面是特性状态片段的 Demo，它显示该特性在最新的 Kubernetes 版本中处于稳定状态。
+
+```
+{{</* feature-gate-description name="DryRun" */>}}
+```
+
+<!--
+Renders to:
+-->
+渲染到：
+
+{{< feature-gate-description name="DryRun" >}}
+
 <!--
 ## Glossary
 There are two glossary shortcodes: `glossary_tooltip` and `glossary_definition`.
@@ -184,7 +216,6 @@ The content of the `page` parameter is the suffix of the URL of the API referenc
 -->
 本语句中 `page` 参数的内容是 API 参考页面的 URL 后缀。
 
-
 <!--
 You can link to a specific place into a page by specifying an `anchor`
 parameter, for example to the {{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}}
@@ -208,15 +239,13 @@ example by linking to the
 {{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variables">}}
 section of the page:
 -->
-你可以通过指定 `text` 参数来更改链接的文本，例如通过链接到页面的
-{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="环境变量">}}
-部分：
+你可以通过指定 `text` 参数来更改链接的文本，
+例如通过链接到页面的{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="环境变量">}}部分：
 
 ```
 {{</* api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="环境变量" */>}}
 ```
 
-
 <!--
 ## Table captions
 
@@ -285,8 +314,8 @@ after the opening `<table>` element:
 <caption style="display: none;">Configuration parameters</caption>
 ```
 -->
-如果你查看表格的 HTML 输出结果，你会看到 `<table>` 元素
-后面紧接着下面的元素：
+如果你查看表格的 HTML 输出结果，你会看到 `<table>`
+元素后面紧接着下面的元素：
 
 ```html
 <caption style="display: none;">配置参数</caption>
@@ -390,7 +419,7 @@ println "This is tab 2."
 ```go-html-template
 {{</* tabs name="tab_with_md" >}}
 {{% 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 文件）时，在 `<LANG>/examples/`
 子目录之一中创建该文件，其中 `<LANG>` 是页面的语言。
-在你的页面的 markdown 文本中，使用 `code` 短代码：
+在你的页面的 Markdown 文本中，使用 `code` 短代码：
 
 ```none
 {{%/* code_sample file="<RELATIVE-PATH>/example-yaml>" */%}}
@@ -661,7 +690,8 @@ Renders to:
 -->
 ### `{{</* latest-semver */>}}`
 
-`{{</* latest-semver */>}}` 短代码可以生成站点参数 `latest` 不含前缀 `v` 的版本号取值。
+`{{</* latest-semver */>}}` 短代码可以生成站点参数 `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)