From 78131fd58dc19a2c42ed1f0ef2ff65bc806a7ef5 Mon Sep 17 00:00:00 2001 From: my-git9 Date: Thu, 15 Jun 2023 15:02:11 +0800 Subject: [PATCH] [zh] improve build code-blocks diagrams (#13369) Signed-off-by: xin.li --- .../docs/releases/contribute/build/index.md | 30 ++++++--- .../releases/contribute/code-blocks/index.md | 66 ++++++++++++------- .../releases/contribute/diagrams/index.md | 9 +-- 3 files changed, 68 insertions(+), 37 deletions(-) diff --git a/content/zh/docs/releases/contribute/build/index.md b/content/zh/docs/releases/contribute/build/index.md index 433ff666a8..5c50f6882b 100644 --- a/content/zh/docs/releases/contribute/build/index.md +++ b/content/zh/docs/releases/contribute/build/index.md @@ -5,11 +5,15 @@ weight: 5 keywords: [contribute, serve, Docker, Hugo, build] --- -在为本站做贡献之后，要确保变更是符合预期的。可以通过做本地预览来确保没问题，我们提供了相应的工具让您方便地构建和查看。我们使用了自动化测试来检测所有贡献的质量。在把修改的内容放在一个合并请求（PR）中提交之前，您也应该在本地运行测试。 +在为本站做贡献之后，要确保变更是符合预期的。可以通过做本地预览来确保没问题， +我们提供了相应的工具让您方便地构建和查看。我们使用了自动化测试来检测所有贡献的质量。 +在把修改的内容放在一个合并请求（PR）中提交之前，您也应该在本地运行测试。 ## 开始之前 {#before-you-begin} -为了保证本地运行测试的工具和 Istio 持续集成（CI）运行测试的工具是相同的版本，我们提供了一个包含了所有需要工具的 Docker 镜像，包括了我们站点的生成器：[Hugo](https://gohugo.io/)。 +为了保证本地运行测试的工具和 Istio 持续集成（CI）运行测试的工具是相同的版本， +我们提供了一个包含了所有需要工具的 Docker 镜像，包括了我们站点的生成器： +[Hugo](https://gohugo.io/)。 为了本地构建，测试和预览站点，要在您的系统上安装 [Docker](https://www.docker.com/get-started)。 @@ -21,19 +25,23 @@ keywords: [contribute, serve, Docker, Hugo, build] $ make serve {{< /text >}} -如果您的修改没有出现编译错误，这个命令会构建这个站点，并且启动一个本地 web 服务来运行这个站点。通过在浏览器中输入 `http://localhost:1313` 来浏览本地构建的站点。 +如果您的修改没有出现编译错误，这个命令会构建这个站点，并且启动一个本地 Web +服务来运行这个站点。通过在浏览器中输入 `http://localhost:1313` 来浏览本地构建的站点。 -如果您要从远程服务器上构建和预览，可以使用 `ISTIO_SERVE_DOMAIN` 来设置这个服务器的 IP 地址或者 DNS 域名，例如： +如果您要从远程服务器上构建和预览，可以使用 `ISTIO_SERVE_DOMAIN` +来设置这个服务器的 IP 地址或者 DNS 域名，例如： {{< text bash >}} $ make ISTIO_SERVE_DOMAIN=192.168.7.105 serve {{< /text >}} -这个例子是在 `192.168.7.105` 这个远程服务器上构建站点并且启动一个 web 服务器。像前面一样，可以通过 `http://192.168.7.105:1313` 这个地址来访问这个 web 服务器。 +这个例子是在 `192.168.7.105` 这个远程服务器上构建站点并且启动一个 Web 服务器。 +像前面一样，可以通过 `http://192.168.7.105:1313` 这个地址来访问这个 Web 服务器。 ### 测试变更 {#test-your-changes} -我们使用静态检测和测试方法，通过自动检查确保网站内容的质量基线。提交的贡献都必须成功通过这些检测才能被批准合入主线。在您提交 PR 之前确保在本地已经运行了这些检查。我们会执行以下自动检查： +我们使用静态检测和测试方法，通过自动检查确保网站内容的质量基线。提交的贡献都必须成功通过这些检测才能被批准合入主线。 +在您提交 PR 之前确保在本地已经运行了这些检查。我们会执行以下自动检查： - HTML 校对：确保所有链接以及其它检查均有效。 - 拼写检查：确保所有内容的拼写都是正确的。 @@ -49,12 +57,16 @@ $ make lint - 有错别字：在 Markdown 文件上修复错别字。 - 报告有命令，字段或者符号名称错误：将带有错误的内容放在反引号中。 -- 因为正确的单词或者名称没有包括在工具词典中而被报告错误：将单词添加到 `istio/istio.io` 根目录下的 `.spelling` 文件中。 +- 因为正确的单词或者名称没有包括在工具词典中而被报告错误：将单词添加到 `istio/istio.io` + 根目录下的 `.spelling` 文件中。 -如果网络链接不稳定，可能会无法使用链接检查器。如果您的网络链接不好，可以设置检查器不检查外部链接。例如：在运行静态检查之前，设置环境变量 `INTERNAL_ONLY` 为 `True`： +如果网络链接不稳定，可能会无法使用链接检查器。如果您的网络链接不好， +可以设置检查器不检查外部链接。例如：在运行静态检查之前，设置环境变量 +`INTERNAL_ONLY` 为 `True`： {{< text bash >}} $ make INTERNAL_ONLY=True lint {{< /text >}} -当您修改的内容通过所有检查，就可以把修改作为 PR 向仓库提交了。更多信息请访问[如何使用 GitHub](/zh/about/contribute/github)。 +当您修改的内容通过所有检查，就可以把修改作为 PR 向仓库提交了。 +更多信息请访问[如何使用 GitHub](/zh/about/contribute/github)。 diff --git a/content/zh/docs/releases/contribute/code-blocks/index.md b/content/zh/docs/releases/contribute/code-blocks/index.md index 3610d7e31a..f6d3664029 100644 --- a/content/zh/docs/releases/contribute/code-blocks/index.md +++ b/content/zh/docs/releases/contribute/code-blocks/index.md @@ -5,11 +5,13 @@ weight: 8 keywords: [contribute, documentation, guide, code-block] --- -Istio 文档中的代码块是嵌入式预定义格式的内容块。我们使用 Hugo 构建网站，并使用 `text` 和 `text_import` 短代码将代码添加到页面中。 +Istio 文档中的代码块是嵌入式预定义格式的内容块。我们使用 Hugo 构建网站，并使用 +`text` 和 `text_import` 短代码将代码添加到页面中。 这样我们可以为读者提供更好的体验。渲染的代码块可以轻松地复制，打印或下载。 -所有的贡献内容都必须使用这些短代码。如果您的内容未使用适当的短代码，则它不会被合并，直到做出适当的修改。该页面包含嵌入式代码块的几个示例以及可用的格式化选项。 +所有的贡献内容都必须使用这些短代码。如果您的内容未使用适当的短代码，则它不会被合并， +直到做出适当的修改。该页面包含嵌入式代码块的几个示例以及可用的格式化选项。 代码块的最常见示例是命令行界面（CLI）命令/指令，例如： @@ -35,7 +37,8 @@ Hello {{}} {{< /text >}} -默认情况下，会给定并设置属性为 `bash`，这些命令将使用 bash 语法高亮显示，并且输出将显示为纯文本，例如： +默认情况下，会给定并设置属性为 `bash`，这些命令将使用 bash 语法高亮显示， +并且输出将显示为纯文本，例如： {{< text bash >}} $ echo "Hello" >file.txt @@ -67,9 +70,10 @@ Hello There {{< /text >}} -您的 {{}}workload{{}} 可以用各种编程语言编码。因此，我们实现了多种对代码块中语法高亮显示的支持。 +您的 {{}}workload{{}} 可以用各种编程语言编码。 +因此，我们实现了多种对代码块中语法高亮显示的支持。 -## 添加语法高亮{#add-syntax-highlighting} +## 添加语法高亮 {#add-syntax-highlighting} 让我们从下面的 “Hello World” 例子开始： @@ -89,7 +93,8 @@ func HelloWorld() { } {{< /text >}} -你可以为代码块中的内容指定语言，以实现语法高亮。上面的例子指定了语法为 `plain`，所有代码块的渲染结果没有任何语法高亮。但是，你可以指定其语法为 `Go`，例如： +您可以为代码块中的内容指定语言，以实现语法高亮。上面的例子指定了语法为 `plain`， +所有代码块的渲染结果没有任何语法高亮。但是，您可以指定其语法为 `Go`，例如： {{< text markdown >}} {{}} @@ -107,7 +112,7 @@ func HelloWorld() { } {{< /text >}} -### 支持的语法{#supported-syntax} +### 支持的语法 {#supported-syntax} Istio 代码块目前支持下面这些语言的语法高亮： @@ -127,7 +132,9 @@ Istio 代码块目前支持下面这些语言的语法高亮： - `docker` - `bash` -默认情况下，CLI 命名的输出结果会按照 plain 文本进行渲染，即没有语法高亮。如果你想为输出添加语法高亮，你可以在短代码中指定语法。在 Istio 中，最常见的例子就是 YAML 和 JSON 的输出结果，例如： +默认情况下，CLI 命名的输出结果会按照 plain 文本进行渲染，即没有语法高亮。 +如果您想为输出添加语法高亮，您可以在短代码中指定语法。在 Istio 中，最常见的例子就是 +YAML 和 JSON 的输出结果，例如： {{< text markdown >}} {{}} @@ -151,11 +158,12 @@ $ kubectl -n istio-system logs $(kubectl -n istio-system get pods -l istio-mixer {"level":"warn","ts":"2017-09-21T04:33:31.233Z","instance":"newlog.logentry.istio-system","destination":"ingress.istio-system.svc.cluster.local","latency":"74.47ms","responseCode":200,"responseSize":5599,"source":"unknown","user":"unknown"} {{< /text >}} -## 将代码动态导入至文档{#dynamically-import-code-into-your-document} +## 将代码动态导入至文档 {#dynamically-import-code-into-your-document} -前面的示例显示了如何格式化文档中的代码。此外，您还可以使用 `text_import` 短代码从文件中导入内容或代码。该文件可以存储在文档存储库中，也可以存储在允许跨域访问（CORS）的外部源中。 +前面的示例显示了如何格式化文档中的代码。此外，您还可以使用 `text_import` +短代码从文件中导入内容或代码。该文件可以存储在文档存储库中，也可以存储在允许跨域访问（CORS）的外部源中。 -### 从 `istio.io` 仓库中的文件导入代码{#import-code-from-repository} +### 从 `istio.io` 仓库中的文件导入代码 {#import-code-from-repository} 使用 `file` 属性，从 Istio 文档仓库中的一个文件中导入内容，例如： @@ -169,28 +177,32 @@ $ kubectl -n istio-system logs $(kubectl -n istio-system get pods -l istio-mixer 通过设置 `syntax=` 字段的值，指定内容的语言，可以获得语法高亮的渲染。 -### 通过 URL 从外部资源导入代码{#import-code-from-an-external-source-through-a-URL} +### 通过 URL 从外部资源导入代码 {#import-code-from-an-external-source-through-a-URL} -类似的，你可以从互联网动态的导入内容。使用 `url` 属性指定资源。下面的例子导入了同一个文件，但它是通过 URL 导入的： +类似的，您可以从互联网动态的导入内容。使用 `url` 属性指定资源。 +下面的例子导入了同一个文件，但它是通过 URL 导入的： {{< text markdown >}} {{}} {{< /text >}} -如你所见，渲染结果跟前面的完全相同： +如您所见，渲染结果跟前面的完全相同： {{< text_import url="https://raw.githubusercontent.com/istio/istio.io/master/test/snippet_example.txt" syntax="plain" >}} -如果文件来自其它网站，请确保目标网站允许跨域访问（CORS）。注意，这里可以使用 GitHub 原始网站（`raw.githubusercontent.com`）的内容。 +如果文件来自其它网站，请确保目标网站允许跨域访问（CORS）。注意，这里可以使用 +GitHub 原始网站（`raw.githubusercontent.com`）的内容。 ### 从较大的文件导入代码片段{#snippets} -有时候，你不需要一个文件的全部内容。此时，您可以使用 _named snippets_ 来控制要渲染该文件的哪一部分。 -用包含 `$snippet SNIPPET_NAME` 和 `$endsnippet` 标签的注释标记代码片段中所需的代码。两个标签之间的内容表示要渲染代码片段。例如，获取以下文件： +有时候，您不需要一个文件的全部内容。此时，您可以使用 **named snippets** +来控制要渲染该文件的哪一部分。用包含 `$snippet SNIPPET_NAME` 和 `$endsnippet` +标签的注释标记代码片段中所需的代码。两个标签之间的内容表示要渲染代码片段。例如，获取以下文件： {{< text_import file="test/snippet_example.txt" syntax="plain" >}} -该文件具有三个单独的代码段：`SNIP1`、`SNIP2` 和 `SNIP3`。约定是使用全大写字母的名称。要引用文档中的特定代码段，请将短代码中 snippet 属性的值设置为代码段的名称，例如： +该文件具有三个单独的代码段：`SNIP1`、`SNIP2` 和 `SNIP3`。约定是使用全大写字母的名称。 +要引用文档中的特定代码段，请将短代码中 snippet 属性的值设置为代码段的名称，例如： {{< text markdown >}} {{}} @@ -200,11 +212,15 @@ $ kubectl -n istio-system logs $(kubectl -n istio-system get pods -l istio-mixer {{< text_import file="test/snippet_example.txt" syntax="plain" snippet="SNIP1" >}} -你还可以使用 `text_import` 短代码的 `syntax` 属性为代码片段指定语法高亮。对于包含 CLI 命令的代码片段，你可以使用 `outputis` 属性为输出结果指定语法高亮。 +您还可以使用 `text_import` 短代码的 `syntax` 属性为代码片段指定语法高亮。 +对于包含 CLI 命令的代码片段，您可以使用 `outputis` 属性为输出结果指定语法高亮。 ## 链接 GitHub 上的文件{#link-2-files} -有些代码块需要引用 [Istio 的 GitHub 仓库](https://github.com/istio/istio)中的文件。其中最常见的情况就是引用 YAML 配置文件。无需将 YAML 文件的全部内容复制到您的代码块中，您可以使用 `@` 符号将文件的相对路径名括起来。此标记会将路径渲染为指向 GitHub 中当前发行版本分支的文件的链接，例如： +有些代码块需要引用 [Istio 的 GitHub 仓库](https://github.com/istio/istio)中的文件。 +其中最常见的情况就是引用 YAML 配置文件。无需将 YAML 文件的全部内容复制到您的代码块中， +您可以使用 `@` 符号将文件的相对路径名括起来。此标记会将路径渲染为指向 GitHub +中当前发行版本分支的文件的链接，例如： {{< text markdown >}} {{}} @@ -218,7 +234,8 @@ $ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@ $ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@ {{< /text >}} -默认情况下，这些链接指向 `istio/istio` 存储库当前发行版的分支。想要让链接指向另一个 Istio 仓库，可以使用 `repo` 属性，例如： +默认情况下，这些链接指向 `istio/istio` 存储库当前发行版的分支。想要让链接指向另一个 +Istio 仓库，可以使用 `repo` 属性，例如： {{< text markdown >}} {{}} @@ -242,7 +259,8 @@ $ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@ ## 高级功能{#advanced-features} -要使用更多下面介绍到的用于预定义格式内容的高级功能，请使用 `text` 序列的扩展形式，而不是到前面介绍和展示的简化形式。展开的表单会使用标准的 HTML 属性： +要使用更多下面介绍到的用于预定义格式内容的高级功能，请使用 `text` 序列的扩展形式， +而不是到前面介绍和展示的简化形式。展开的表单会使用标准的 HTML 属性： {{< text markdown >}} {{}} @@ -263,12 +281,12 @@ $ kubectl -n istio-system logs $(kubectl -n istio-system get pods -l istio-mixer |`url` | 在代码块中显示的文档的 URL。 |`syntax` | 代码块的语法。 |`outputis` | 当语法为 bash 时，该属性指定命令输出结果的语法。 -|`downloadas` | 当用户 [下载该代码块时](#download-name)默认的文件名。 +|`downloadas` | 当用户[下载该代码块时](#download-name)默认的文件名。 |`expandlinks` | 是否在代码块中为 [GitHub 文件引用](#link-2-files)开启链接扩展。 |`snippet` | 要从代码块中提取的内容的 [snippet](#snippets) 名称。 |`repo` | 嵌入代码块中的仓库的 [GitHub 链接](#link-2-files)。 -### 下载名{#download-name} +### 下载名 {#download-name} 您可以使用 `downloadas` 属性定义当某人下载代码块时默认的文件名，例如： diff --git a/content/zh/docs/releases/contribute/diagrams/index.md b/content/zh/docs/releases/contribute/diagrams/index.md index a540bf983e..f06afe9bc9 100644 --- a/content/zh/docs/releases/contribute/diagrams/index.md +++ b/content/zh/docs/releases/contribute/diagrams/index.md @@ -7,9 +7,10 @@ keywords: [contribute,diagram,documentation,guide] 欢迎学习 Istio 图表指南！ -本指南通过一个 [SVG 文件](./diagram-guidelines.svg)或者 [Google Drawings 文件](https://docs.google.com/drawings/d/1f3NyutAQIDOA8ojGNyMA5JAJllDShZGQAFfdD01XdSc/edit)使您可以轻松的复用 shape 和 style。 -通过本指南，您可以使用任何矢量图绘制工具（例如，Google Drawings、Inkscape、Illustrator）为 Istio 站点创建 SVG 图表。 -请保持图表中的文本处于可编辑状态。 +本指南通过一个 [SVG 文件](./diagram-guidelines.svg)或者 +[Google Drawings 文件](https://docs.google.com/drawings/d/1f3NyutAQIDOA8ojGNyMA5JAJllDShZGQAFfdD01XdSc/edit)使您可以轻松的复用 +shape 和 style。通过本指南，您可以使用任何矢量图绘制工具（例如，Google Drawings、Inkscape、Illustrator） +为 Istio 站点创建 SVG 图表。请保持图表中的文本处于可编辑状态。 我们的目标是在站点内的所有图表之间实现一致性，以确保图表是清晰、技术表达准确和易读的。 @@ -29,7 +30,7 @@ keywords: [contribute,diagram,documentation,guide] 1. 图表绘制完成后，将其导出为 SVG 并将该文件提交在您的 PR 中。 1. 在包含图表的 Markdown 文件中留下带有 Google Drawings 文件 URL 的注释。 -如果您的图表包含了过程步骤，**不要在** 图表中 **为步骤添加描述**。 +如果您的图表包含了过程步骤，**不要在**图表中**为步骤添加描述**。 仅需将步骤的编号添加到图表中，并在文档中为步骤的编号添加描述，请确保两者的编号是匹配的。 这种方法使得图表易于理解，内容的可读性也更好。