mirror of https://github.com/istio/istio.io.git
[zh] improve build code-blocks diagrams (#13369)
Signed-off-by: xin.li <xin.li@daocloud.io>
This commit is contained in:
my-git9
GitHub
parent
a09811f5ca
commit
78131fd58d
|
|
@ -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)。
|
||||
|
|
|
|||
|
|
@ -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 */>}}
|
||||
{{< /text >}}
|
||||
|
||||
默认情况下，会给定并设置属性为 `bash`，这些命令将使用 bash 语法高亮显示，并且输出将显示为纯文本，例如：
|
||||
默认情况下，会给定并设置属性为 `bash`，这些命令将使用 bash 语法高亮显示，
|
||||
并且输出将显示为纯文本，例如：
|
||||
|
||||
{{< text bash >}}
|
||||
$ echo "Hello" >file.txt
|
||||
|
|
@ -67,9 +70,10 @@ Hello
|
|||
There
|
||||
{{< /text >}}
|
||||
|
||||
您的 {{<gloss workload>}}workload{{</gloss>}} 可以用各种编程语言编码。因此，我们实现了多种对代码块中语法高亮显示的支持。
|
||||
您的 {{<gloss workload>}}workload{{</gloss>}} 可以用各种编程语言编码。
|
||||
因此，我们实现了多种对代码块中语法高亮显示的支持。
|
||||
|
||||
## 添加语法高亮{#add-syntax-highlighting}
|
||||
## 添加语法高亮 {#add-syntax-highlighting}
|
||||
|
||||
让我们从下面的 “Hello World” 例子开始：
|
||||
|
||||
|
|
@ -89,7 +93,8 @@ func HelloWorld() {
|
|||
}
|
||||
{{< /text >}}
|
||||
|
||||
你可以为代码块中的内容指定语言，以实现语法高亮。上面的例子指定了语法为 `plain`，所有代码块的渲染结果没有任何语法高亮。但是，你可以指定其语法为 `Go`，例如：
|
||||
您可以为代码块中的内容指定语言，以实现语法高亮。上面的例子指定了语法为 `plain`，
|
||||
所有代码块的渲染结果没有任何语法高亮。但是，您可以指定其语法为 `Go`，例如：
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</* text go */>}}
|
||||
|
|
@ -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 >}}
|
||||
{{</* text bash json */>}}
|
||||
|
|
@ -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_import url="https://raw.githubusercontent.com/istio/istio.io/master/test/snippet_example.txt" syntax="plain" */>}}
|
||||
{{< /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 >}}
|
||||
{{</* text_import file="test/snippet_example.txt" syntax="plain" snippet="SNIP1" */>}}
|
||||
|
|
@ -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 >}}
|
||||
{{</* text bash */>}}
|
||||
|
|
@ -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 >}}
|
||||
{{</* text syntax="bash" repo="api" */>}}
|
||||
|
|
@ -242,7 +259,8 @@ $ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
|
|||
|
||||
## 高级功能{#advanced-features}
|
||||
|
||||
要使用更多下面介绍到的用于预定义格式内容的高级功能，请使用 `text` 序列的扩展形式，而不是到前面介绍和展示的简化形式。展开的表单会使用标准的 HTML 属性：
|
||||
要使用更多下面介绍到的用于预定义格式内容的高级功能，请使用 `text` 序列的扩展形式，
|
||||
而不是到前面介绍和展示的简化形式。展开的表单会使用标准的 HTML 属性：
|
||||
|
||||
{{< text markdown >}}
|
||||
{{</* text syntax="bash" outputis="json" */>}}
|
||||
|
|
@ -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` 属性定义当某人下载代码块时默认的文件名，例如：
|
||||
|
||||
|
|
|
|||
|
|
@ -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 的注释。
|
||||
|
||||
如果您的图表包含了过程步骤，**不要在** 图表中 **为步骤添加描述**。
|
||||
如果您的图表包含了过程步骤，**不要在**图表中**为步骤添加描述**。
|
||||
仅需将步骤的编号添加到图表中，并在文档中为步骤的编号添加描述，请确保两者的编号是匹配的。
|
||||
这种方法使得图表易于理解，内容的可读性也更好。
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue