istio
/
istio.io
mirror of https://github.com/istio/istio.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

zh-translation: ServiceMesher#1735 and others (#6441) 

* fix glossary

* zh-translation: /blog/2020/_index.md #1735

* sync, edit and delete
This commit is contained in:
2BFL 2020-02-11 19:47:31 +08:00 committed by GitHub
parent e643f5a931
commit ab99298346
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 297 additions and 769 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

179
content/zh/about/contribute/add-content/index.md Normal file
View File

@ -0,0 +1,179 @@
---
title: Add New Documentation
description: Details how to contribute new documentation to Istio.
weight: 3
aliases:
- /zh/docs/welcome/contribute/writing-a-new-topic.html
- /zh/docs/reference/contribute/writing-a-new-topic.html
- /zh/about/contribute/writing-a-new-topic.html
- /zh/create
keywords: [contribute]
---
To contribute new documentation to Istio, just follow these steps:
1. Identify the audience and intended use for the information.
1. Choose the [type of content](#content-types) you wish to contribute.
1. [Choose a title](#choosing-a-title).
1. Write your contribution following our [documentation contribution guides](/zh/about/contribute).
1. Submit your contribution to our [GitHub repository](https://github.com/istio/istio.io).
1. Follow our [review process](/zh/about/contribute/review) until your contribution
is merged.
## Identify the audience and intended use
The best documentation starts by knowing the intended readers, their knowledge,
and what you expect them to do with the information. Otherwise, you cannot
determine the appropriate scope and depth of information to provide, its ideal
structure, or the necessary supporting information. The following examples show
this principle in action:
- The reader needs to perform a specific task: Tell them how to recognize when
the task is necessary and provide the task itself as a list of numbered steps,
don’t simply describe the task in general terms.
- The reader must understand a concept before they can perform a task: Before
the task, tell them about the prerequisite information and provide a link to
it.
- The reader needs to make a decision: Provide the conceptual information
necessary to know when to make the decision, the available options, and when
to choose one option instead of the other.
- The reader is an administrator but not a SWE: Provide a script,
not a link to a code sample in a developer’s guide.
- The reader needs to extend the features of the product: Provide an example of
how to extend the feature, using a simplified scenario for illustration
purposes.
- The reader needs to understand complex feature relationships: Provide a
diagram showing the relationships, rather than writing multiple pages of
content that is tedious to read and understand.
The most important thing to avoid is the common mistake of simply
giving readers all the information you have, because you are unsure about
what information they need.
If you need help identifying the audience for you content, we are happy to help
and answer all your questions during the [Docs Working Group](https://github.com/istio/community/blob/master/WORKING-GROUPS.md#istio-working-groups)
biweekly meetings.
## Content types
When you understand the audience and the intended use for the information you
provide, you can choose content type that best addresses their needs. To make it
easy for you to choose, the following table shows the supported content types,
their intended audiences, and the goals each type strives to achieve:
<table>
<thead>
<tr>
<th>Content type</th>
<th>Goals</th>
<th>Audiences</th>
</tr>
</thead>
<tr>
<td>Concepts</td>
<td>Explain some significant aspect of Istio. For example, a concept page
describes the configuration model of a feature and explains its functionality.
Concept pages don't include sequences of steps. Instead, provide links to
corresponding tasks.</td>
<td>Readers that want to understand how features work with only basic
knowledge of the project.</td>
</tr>
<tr>
<td>Reference pages</td>
<td>Provide exhaustive and detailed technical information. Common examples
include API parameters, command-line options, configuration settings, and
advanced procedures. Reference content is generated from the Istio code
base and tested for accuracy.
</td>
<td>Readers with advanced and deep technical knowledge of the project that
needs specific bits of information to complete advanced tasks.</td>
</tr>
<tr>
<td>Examples</td>
<td>Describe a working and stand-alone example that highlights a set of
features, an integration of Istio with other projects, or an end-to-end
solution for a use case. Examples must use an existing Istio setup as a
starting point. Examples must include an automated test since they are maintained for technical accuracy.
</td>
<td>Readers that want to quickly run the example themselves and
experiment. Ideally, readers should be able to easily change the example
to produce their own solutions.</td>
</tr>
<tr>
<td>Tasks</td>
<td>Shows how to achieve a single goal using Istio features. Tasks contain procedures written
as a sequence of steps. Tasks provide minimal
explanation of the features, but include links to the concepts that
provide the related background and knowledge. Tasks must include automated
tests since they are tested and maintained for technical accuracy.</td>
<td>Readers that want to use Istio features.</td>
</tr>
<tr>
<td>Setup pages</td>
<td>Focus on the installation steps needed to complete an Istio
deployment. Setup pages must include automated tests since they are tested and maintained for technical accuracy.
</td>
<td>New and existing Istio users that want to complete a deployment.</td>
</tr>
<tr>
<td>Blog posts</td>
<td>
Focus on Istio or products and technologies related to it. Blog posts fall in one of the following three categories:
<ul>
<li>Posts detailing the author’s experience using and configuring Istio, especially those that articulate a novel experience or perspective.</li>
<li>Posts highlighting Istio features.</li>
<li>Posts detailing how to accomplish a task or fulfill a specific use case using Istio. Unlike Tasks and Examples, the technical accuracy of blog posts is not maintained and tested after publication.</li>
</ul>
</td>
<td>Readers with a basic understanding of the project who want to learn
about it in an anecdotal, experiential, and more informal way.</td>
</tr>
<tr>
<td>News entries</td>
<td>
Focus on timely information about Istio and related events. News entries typically announce new releases or upcoming events.
</td>
<td>Readers that want to quickly learn what's new and what's happening in
the Istio community.</td>
</tr>
<tr>
<td>FAQ entries</td>
<td>
Provide quick answers to common questions. Answers don't introduce any
concepts. Instead, they provide practical advice or insights. Answers
must link to tasks, concepts, or examples in the documentation for readers to learn more.
</td>
<td>Readers with specific questions who are looking for brief answers and
resources to learn more.</td>
</tr>
<tr>
<td>Operation guides</td>
<td>
Focus on practical solutions that address specific problems encountered while running Istio in a real-world setting.
</td>
<td>Service mesh operators that want to fix problems or implement
solutions for running Istio deployments.</td>
</tr>
</table>
## Choosing a title
Choose a title for your topic that has the keywords you want search engines to
find. All content files in Istio are named `index.md`, but each content file is
within a folder that uses the keywords in the topic's title,
separated by hyphens, all in lowercase. Keep folder names as short as possible
to make cross-references easier to create and maintain.
## Submit your contribution to GitHub
If you are not familiar with GitHub, see our [working with GitHub guide](/zh/about/contribute/github)
to learn how to submit documentation changes.
If you want to learn more about how and when your contributions are published,
see the [section on branching](/zh/about/contribute/github#branching-strategy) to understand
how we use branches and cherry picking to publish our content.

764
content/zh/about/contribute/creating-and-editing-pages/index.md
View File

@ -1,764 +0,0 @@
---
title: 创建和编辑页面
description: 介绍创建和维护文档页面的机制。
weight: 10
aliases:
- /zh/docs/welcome/contribute/writing-a-new-topic.html
- /zh/docs/reference/contribute/writing-a-new-topic.html
- /zh/about/contribute/writing-a-new-topic.html
- /zh/create
keywords: [contribute]
---
此页面介绍了如何创建、测试和维护 Istio 文档主题。
## 开始之前{#before-you-begin}
在开始编写 Istio 文档之前，首先需要创建一个 Istio 文档存储库的分支正如[使用 GitHub 工作](/zh/about/contribute/github/)中所述。
## 选择页面类型{#choosing-a-page-type}
在准备编写一个新主题时，请考虑您的内容最适合以下哪种页面类型：
<table>
<tr>
<td>概念</td>
<td>概念页面解释了 Istio 的一些重要概念。例如，概念页面可能会描述 Mixer 的配置模型并解释其中的一些细微之处。通常，概念页面不包括具体的操作步骤，而是提供指向任务的链接。</td>
</tr>
<tr>
<td>参考</td>
<td>参考页面提供了诸如 API 参数、命令行选项、配置设置和过程之类的详尽列表。</td>
</tr>
<tr>
<td>示例</td>
<td>示例页面描述了一个完整工作的独立示例，突出显示了一组特定功能。示例必须具有易于遵循的设置和使用说明，以便用户可以自己快速运行示例并尝试更改示例以探索系统。测试和维护示例以获得技术准确性。</td>
</tr>
<tr>
<td>任务</td>
<td>任务页面显示如何执行单个操作，通常通过提供一系列简短的步骤。任务页面具有最少的解释，但通常提供指向提供相关背景和知识的概念主题的链接。测试和维护任务以确保技术准确性。</td>
</tr>
<tr>
<td>安装</td>
<td>安装页面类似于任务页面，但它侧重于安装活动。测试和维护安装页面以确保技术准确性。</td>
</tr>
<tr>
<td>博客文章</td>
<td>
博客文章是关于 Istio 或与之相关的产品和技术的文章。通常，博客属于以下 3 个类别之一：
<ul>
<li>详细介绍了作者使用和配置 Istio 的经验，特别是能够表达新颖体验或观点的那些博客。</li>
<li>突出显示了 Istio 功能的博客。</li>
<li>详细介绍如何使用 Istio 完成任务或实现特定用例的文章。与任务和示例不同，博客文章的技术准确性在发布后不会得到维护和测试。</li>
</ul>
</td>
</tr>
<tr>
<td>新闻条目</td>
<td>
新闻条目是有关 Istio 及其相关事件的及时文章。新闻条目通常会宣布新版本或即将发生的事件。
</td>
</tr>
<tr>
<td>FAQ</td>
<td>
FAQ 条目用于快速解答常见的客户问题。答案通常不会引入任何新概念，而是仅侧重于一些实用的建议或见解，并提供了供用户了解更多信息的指向主文档的链接。
</td>
</tr>
<tr>
<td>运维指南</td>
<td>
有关解决在实际环境中运行 Istio 时遇到的特定问题的实用解决方案。
</td>
</tr>
</table>
## 命名主题{#naming-a-topic}
为您的主题选择一个具有您希望搜索引擎查找的关键字的标题。为你的主题创建一个使用标题中的单词、并用连字符分隔而且所有字母均小写的文件名。
## 设置文档的元数据信息{#updating-front-matter}
每个文档文件都需要从头开始写[元数据信息](https://gohugo.io/content-management/front-matter/)。元数据信息是介于两个 YAML 块之间通过 3 个“-”分割的信息。下面就是你需要填写的元数据信息:
{{< text yaml >}}
---
title: <title>
description: <description>
weight: <weight>
keywords: [keyword1,keyword2,...]
---
{{< /text >}}
在新的 markdown 文件的开头复制上面的内容并更新信息字段。可用的字段如下：
|字段 | 描述
|-------------------|------------
|`title` | 页面短标题
|`linktitle` | 页面的备用标题（通常较短），在侧栏中用于引用页面
|`subtitle` | 可选子标题，显示在主标题下方
|`description` | 关于页面内容的单行描述
|`icon` | 图像文件的可选路径，该路径显示在主标题旁边
|`weight` | 一个整数，用于确定此页面相对于同一目录中其他页面的排序顺序
|`keywords` | 描述页面的关键字数组，用于创建“另请参见”链接的网络
|`draft` | 如果为 true，则阻止页面显示在任何导航区域中
|`aliases` | 有关此项目的详细信息，请参见下面的[重命名，移动或删除页面](#renaming-moving-or-deleting-pages)。
|`skip_byline` | 将此属性设置为 true 可以防止页面在主标题下带有下划线
|`skip_seealso` | 将此设置为 true 可以防止页面为其生成“另请参见”部分
一些字段控制大多数页面上自动生成的目录：
|字段 | 描述
|--------------------|------------
|`skip_toc` | 将其设置为 true 可以防止页面为其生成目录
|`force_inline_toc` | 将此属性设置为 true 可强制将生成的目录插入到文本中，而不是在边栏中
|`max_toc_level` | 设置为 2、3、4、5 或 6 表示要在目录中显示的最大标题级别
|`remove_toc_prefix` | 将其设置为一个字符串，该字符串将从目录中每个条目的开头删除（如果存在）
一些针对章节页面的属性字段（例如，用于文章排版的文件 `_index.md`）：
|字段 | 描述
|----------------------|------------
|`skip_list` | 将此设置为 true 可以防止在部分页面上自动生成内容
|`simple_list` | 将此属性设置为 true 可将简单的列表布局而不是图库布局用于节页面的自动生成的内容
|`list_below` | 将此属性设置为 true 可将自动生成的内容插入到手动编写的内容下方的部分页面中
|`list_by_publishdate` | 将此属性设置为 true 可以按发布日期而不是按页面权重对页面上生成的内容进行排序
还有一些专门用于博客文章的元数据字段：
|字段 | 描述
|----------------|------------
|`publishdate` | 帖子原始发表日期
|`last_update` | 上次重大修改的日期
|`attribution` | 帖子作者的姓名（可选）
|`twitter` | 帖子作者的 Twitter 账号（可选）
|`target_release`| 发布此博客时要牢记这一点（通常是创作或更新该博客时当前的主要 Istio 版本）
## 添加图片{#adding-images}
将图片文件与 markdown 文件放在同一目录中。首选的图片格式是 SVG。在 markdown 文件中，使用以下代码添加图片：
{{< text html >}}
{{</* image width="75%" ratio="45.34%"
link="./myfile.svg"
alt="Alternate text to display when the image can't be loaded"
title="A tooltip displayed when hovering over the image"
caption="A caption displayed under the image"
*/>}}
{{< /text >}}
`link` 和 `caption` 是必填项，其他为可选。
如果没有提供 `title` 值，它将默认与 `caption` 的值相同。如果没有提供 `alt` 值，它就会默认为 `title` 或 `caption`（如果 title 没有定义）的值。
`width` 表示图像相对于周围文本使用的空间百分比。如果未指定该值，则默认为100％。
`ratio` 表示图像高度与图像宽度之比。该值是针对任一本地图像内容自动计算的，但是在引用外部图像内容时必须手动计算。在这种情况下，比率应设置为（图像高度/图像宽度）\* 100。
## 添加图标{#adding-icons}
您可以使用以下方法在内容中嵌入一些常用图标：
{{< text markdown >}}
{{</* warning_icon */>}}
{{</* idea_icon */>}}
{{</* checkmark_icon */>}}
{{</* cancel_icon */>}}
{{</* tip_icon */>}}
{{< /text >}}
看起来像 {{< warning_icon >}}、{{< idea_icon >}}、{{< checkmark_icon >}}、{{< cancel_icon >}} 和 {{< tip_icon >}} 这样。
## 链接到其他页面{#linking-to-other-pages}
文档中可以包含三种类型的链接。每种方法都使用不同的方式来指示链接目标：
1. **互联网链接**。您使用经典的 URL 语法（最好与 HTTPS 协议一起使用）来引用 Internet 上的文件：
{{< text markdown >}}
[看这里](https://mysite/myfile.html)
{{< /text >}}
1. **相对链接**。您可以使用以句点开头的相对链接来引用与当前文件处于同一级别或站点层次结构中以下的任何内容：
{{< text markdown >}}
[看这里](./adir/anotherfile.html)
{{< /text >}}
1. **绝对链接**。您可以使用以 `/` 开头的绝对链接来引用当前层次结构之外的内容：
{{< text markdown >}}
[看这里](/zh/docs/adir/afile/)
{{< /text >}}
### GitHub{#GitHub}
有几种方法可以从 GitHub 引用文件：
- **{{</* github_file */>}}** 是您在 GitHub 中引用单个文件（例如 yaml 文件）的方式。这产生了一个链接指向 `https://raw.githubusercontent.com/istio/istio*`
{{< text markdown >}}
[liveness]({{</* github_file */>}}/samples/health-check/liveness-command.yaml)
{{< /text >}}
- **{{</* github_tree */>}}** 是您在 GitHub 中引用目录树的方式。这产生了一个链接指向 `https://github.com/istio/istio/tree*`
{{< text markdown >}}
[httpbin]({{</* github_tree */>}}/samples/httpbin)
{{< /text >}}
- **{{</* github_blob */>}}** 是您在 GitHub 源中引用文件的方式。这产生了一个链接指向 `https://github.com/istio/istio/blob*`
{{< text markdown >}}
[RawVM MySQL]({{</* github_blob */>}}/samples/rawvm/README.md)
{{< /text >}}
相对于文档当前对应的分支，以上注释产生指向 GitHub 中相应分支的链接。如果您需要手动构建 URL，可以使用 `{{</* source_branch_name */>}}` 来获取当前目标分支的名称。
## 版本信息{#version-information}
您可以使用 `{{</* istio_version */>}}` 或 `{{</* istio_full_version */>}}`（分别呈现为 {{< istio_version >}} 和 {{< istio_full_version >}}）获得网站描述的当前 Istio 版本。
`{{</* source_branch_name */>}}` 扩展为网站所对应的 `istio/istio` GitHub 仓库的分支名称，这呈现为 {{< source_branch_name >}}。
## 嵌入预格式化的块{#embedding-preformatted-blocks}
您可以使用 `text` 模块嵌入预格式化的内容块：
{{< text markdown >}}
{{</* text plain */>}}
func HelloWorld() {
fmt.Println("Hello World")
}
{{</* /text */>}}
{{< /text >}}
上面产生这种输出：
{{< text plain >}}
func HelloWorld() {
fmt.Println("Hello World")
}
{{< /text >}}
您必须在预格式化的块中指示内容的语法。上方代码块被标记为 `plain`，表示不应对该块应用语法渲染。与上面使用同样的代码块，但现在使用 Go 语言语法进行了注解：
{{< text markdown >}}
{{</* text go */>}}
func HelloWorld() {
fmt.Println("Hello World")
}
{{</* /text */>}}
{{< /text >}}
渲染效果如下：
{{< text go >}}
func HelloWorld() {
fmt.Println("Hello World")
}
{{< /text >}}
支持的语法有 `plain`、`markdown`、`yaml`、`json`、`java`、`javascript`、`c`、`cpp`、`csharp`、`go`、`html`、`protobuf`、`perl`、`docker`、和 `bash`。
### 命令行{#command-lines}
显示一个或多个 bash 命令行时，您可以以 $ 作为每行命令的开头 ：
{{< text markdown >}}
{{</* text bash */>}}
$ echo "Hello"
{{</* /text */>}}
{{< /text >}}
渲染后的效果如下：
{{< text bash >}}
$ echo "Hello"
{{< /text >}}
您可以根据需要设置任意数量的命令行，但是只能识别出一小部分输出。
{{< text markdown >}}
{{</* text bash */>}}
$ echo "Hello" >file.txt
$ cat file.txt
Hello
{{</* /text */>}}
{{< /text >}}
渲染后的效果如下：
{{< text bash >}}
$ echo "Hello" >file.txt
$ cat file.txt
Hello
{{< /text >}}
您还可以在命令行中使用行继续：
{{< text markdown >}}
{{</* text bash */>}}
$ echo "Hello" \
>file.txt
$ echo "There" >>file.txt
$ cat file.txt
Hello
There
{{</* /text */>}}
{{< /text >}}
渲染后的效果如下：
{{< text bash >}}
$ echo "Hello" \
>file.txt
$ echo "There" >>file.txt
$ cat file.txt
Hello
There
{{< /text >}}
默认情况下，使用 `plain` 语法处理输出部分。如果输出使用众所周知的语法，则可以对其进行指定并为其着色。这对于 YAML 或 JSON 输出尤其常见：
{{< text markdown >}}
{{</* text bash json */>}}
$ kubectl -n istio-system logs $(kubectl -n istio-system get pods -l istio-mixer-type=telemetry -o jsonpath='{.items[0].metadata.name}') mixer | grep \"instance\":\"newlog.logentry.istio-system\"
{"level":"warn","ts":"2017-09-21T04:33:31.249Z","instance":"newlog.logentry.istio-system","destination":"details","latency":"6.848ms","responseCode":200,"responseSize":178,"source":"productpage","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.291Z","instance":"newlog.logentry.istio-system","destination":"ratings","latency":"6.753ms","responseCode":200,"responseSize":48,"source":"reviews","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.263Z","instance":"newlog.logentry.istio-system","destination":"reviews","latency":"39.848ms","responseCode":200,"responseSize":379,"source":"productpage","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.239Z","instance":"newlog.logentry.istio-system","destination":"productpage","latency":"67.675ms","responseCode":200,"responseSize":5599,"source":"ingress.istio-system.svc.cluster.local","user":"unknown"}
{"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 */>}}
{{< /text >}}
渲染后的效果如下：
{{< text bash json >}}
$ kubectl -n istio-system logs $(kubectl -n istio-system get pods -l istio-mixer-type=telemetry -o jsonpath='{.items[0].metadata.name}') mixer | grep \"instance\":\"newlog.logentry.istio-system\"
{"level":"warn","ts":"2017-09-21T04:33:31.249Z","instance":"newlog.logentry.istio-system","destination":"details","latency":"6.848ms","responseCode":200,"responseSize":178,"source":"productpage","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.291Z","instance":"newlog.logentry.istio-system","destination":"ratings","latency":"6.753ms","responseCode":200,"responseSize":48,"source":"reviews","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.263Z","instance":"newlog.logentry.istio-system","destination":"reviews","latency":"39.848ms","responseCode":200,"responseSize":379,"source":"productpage","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.239Z","instance":"newlog.logentry.istio-system","destination":"productpage","latency":"67.675ms","responseCode":200,"responseSize":5599,"source":"ingress.istio-system.svc.cluster.local","user":"unknown"}
{"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 >}}
### 扩展形式{#expanded-form}
要使用以下各节中描述的用于预格式化内容的更高级功能，必须使用 `text` 序列的扩展形式，而不是到目前为止显示的简化形式。扩展形式使用普通的HTML属性：
{{< text markdown >}}
{{</* text syntax="bash" outputis="json" */>}}
$ kubectl -n istio-system logs $(kubectl -n istio-system get pods -l istio-mixer-type=telemetry -o jsonpath='{.items[0].metadata.name}') mixer | grep \"instance\":\"newlog.logentry.istio-system\"
{"level":"warn","ts":"2017-09-21T04:33:31.249Z","instance":"newlog.logentry.istio-system","destination":"details","latency":"6.848ms","responseCode":200,"responseSize":178,"source":"productpage","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.291Z","instance":"newlog.logentry.istio-system","destination":"ratings","latency":"6.753ms","responseCode":200,"responseSize":48,"source":"reviews","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.263Z","instance":"newlog.logentry.istio-system","destination":"reviews","latency":"39.848ms","responseCode":200,"responseSize":379,"source":"productpage","user":"unknown"}
{"level":"warn","ts":"2017-09-21T04:33:31.239Z","instance":"newlog.logentry.istio-system","destination":"productpage","latency":"67.675ms","responseCode":200,"responseSize":5599,"source":"ingress.istio-system.svc.cluster.local","user":"unknown"}
{"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 */>}}
{{< /text >}}
可用的属性是：
| 属性 | 描述
|--------------|------------
|`file` | 在预格式化块中显示的文件的路径。
|`url` | 在预格式化块中显示的文档的URL。
|`syntax` | 预格式化块的语法。
|`outputis` | 当语法为 `bash` 时，它指定命令输出的语法。
|`downloadas` | 用户[下载预格式化的块](#download-name)时使用的默认文件名。
|`expandlinks` | 是否在预格式化的块中扩展 [GitHub 文件引用](#links-to-GitHub-files)。
|`snippet` | 从预格式化块中提取的内容[片段](#snippets)的名称。
|`repo` | 用于 [GitHub 链接](#links-to-GitHub-files)的存储库，嵌入到预格式化的块中。
### 内联与导入内容{#inline-vs-imported-content}
到目前为止，您已经看到了内联预格式化内容的示例，但是也可以从文档存储库中的文件或从互联网上的任意 URL 导入内容。为此，您使用 `text_import` 序列。
您可以将 `text_import` 与 `file` 属性一起使用，以引用文档存储库中的文件：
{{< text markdown >}}
{{</* text_import file="test/snippet_example.txt" syntax="plain" */>}}
{{< /text >}}
渲染后的效果如下：
{{< text_import file="test/snippet_example.txt" syntax="plain" >}}
您可以通过类似的方式动态地从互联网提取内容，但是使用 `url` 属性而不是 `file` 属性。这是相同的文件，但是是动态地从URL检索的，而不是静态地引入 HTML 的：
{{< 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`）。
### 下载名称{#download-name}
您可以使用 `downloadas` 属性控制用户选择下载预格式化内容时浏览器使用的名称。例如：
{{< text markdown >}}
{{</* text syntax="go" downloadas="hello.go" */>}}
func HelloWorld() {
fmt.Println("Hello World")
}
{{</* /text */>}}
{{< /text >}}
如果您未指定下载名称，则内联内容将根据当前页面的标题自动导出，下载内容的名称将根据文件名称或 URL 自动导出。
### 链接到 GitHub 文件{#links-to-GitHub-files}
如果您预先格式化的内容引用了 Istio 的 GitHub 存储库中的文件，则可以在文件的相对路径名周围加上一对 @ 符号。这些指示路径应呈现为来自 GitHub 当前分支的文件链接。例如：
{{< text markdown >}}
{{</* text bash */>}}
$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
{{</* /text */>}}
{{< /text >}}
渲染后的效果如下：
{{< text bash >}}
$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
{{< /text >}}
通常，链接将指向 `istio/istio` 存储库的当前发行版分支。如果您想要一个指向其他 Istio 存储库的链接，则可以使用 `repo` 属性：
{{< text markdown >}}
{{</* text syntax="bash" repo="operator" */>}}
$ cat @README.md@
{{</* /text */>}}
{{< /text >}}
渲染后的效果如下：
{{< text syntax="bash" repo="operator" >}}
$ cat @README.md@
{{< /text >}}
如果您的预格式化内容碰巧将 @ 符号用于其他内容，则可以使用 `expandlinks` 属性关闭链接扩展：
{{< text markdown >}}
{{</* text syntax="bash" expandlinks="false" */>}}
$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
{{</* /text */>}}
{{< /text >}}
### 片段{#snippets}
使用导入的内容时，可以使用_命名的片段_（代表文件的各个部分）来控制呈现内容的哪些部分。您可以使用 `$snippets` 批注和成对的 `$endsnippet` 批注在文件中声明代码段。两个注释之间的内容代表代码段。例如，您可能有一个文本文件，如下所示：
{{< text_import file="test/snippet_example.txt" syntax="plain" >}}
然后在 markdown 文件中，您可以使用 `snippet` 属性引用特定的代码段，例如：
{{< text markdown >}}
{{</* text_import file="test/snippet_example.txt" syntax="plain" snippet="SNIP1" */>}}
{{< /text >}}
渲染后的效果如下：
{{< text_import file="test/snippet_example.txt" syntax="plain" snippet="SNIP1" >}}
在文本文件中，代码段可以指示代码段内容的语法，对于 bash 语法，代码段可以包括输出的语法。例如：
{{< text plain >}}
$snippet MySnippetFile.txt syntax="bash" outputis="json"
{{< /text >}}
## 术语表{#glossary-terms}
在页面中首次引入专用的 Istio 术语时，希望在术语表中对其进行注释。这将产生特殊的渲染，邀请用户单击该术语以获取带有定义的弹出窗口。
{{< text markdown >}}
Mixer 使用{{</*gloss*/>}}适配器{{</*/gloss*/>}}来连接后端。
{{< /text >}}
效果如下：
Mixer 使用{{<gloss>}}适配器{{</gloss>}}来连接后端。
如果页面上显示的术语与词汇表中的条目不完全匹配，则可以指定替代项：
{{< text markdown >}}
Mixer 使用{{</*gloss 适配器*/>}}adapter{{</*/gloss*/>}}来连接后端。
{{< /text >}}
which looks like:
Mixer 使用 {{<gloss 适配器>}}adapter{{</gloss>}} 来连接后端。
因此，即使词汇表条目用于**适配器**，也可以在文本中使用**适配器**的英文形式 **adapter**。
## 标注{#callouts}
您可以通过突出显示警告、提示、技巧和引号来特别关注内容块：
{{< text markdown >}}
{{</* warning */>}}
这是一个重要的警告
{{</* /warning */>}}
{{</* idea */>}}
这是一个好主意
{{</* /idea */>}}
{{</* tip */>}}
这是专家的有用提示
{{</* /tip */>}}
{{</* quote */>}}
这是源自某处的引用
{{</* /quote */>}}
{{< /text >}}
which looks like:
{{< warning >}}
这是一个重要的警告
{{< /warning >}}
{{< idea >}}
这是一个好主意
{{< /idea >}}
{{< tip >}}
这是专家的有用提示
{{< /tip >}}
{{< quote >}}
这是源自某处的引用
{{< /quote >}}
请谨慎使用这些标注。标注旨在向用户提供特别提示，并且在整个站点中过度使用它们可以抵消其特别吸引人的性质。
## 嵌入样板文字{#embedding-boilerplate-text}
您可以使用 `boilerplate` 序列将通用样板文本嵌入到任何 markdown 输出中：
{{< text markdown >}}
{{</* boilerplate example */>}}
{{< /text >}}
效果如下：
{{< boilerplate example >}}
您提供了要在当前位置插入的样板文件的名称。可用的样板位于 `boilerplates` 目录中。样板只是正常的 markdown 文件。
## 使用标签{#using-tabs}
如果您要以多种格式显示某些内容，则使用选项卡集并以不同的选项卡显示每种格式会很方便。要插入选项卡式内容，请结合使用 `tabset` 和 `tabs` 注解：
{{< text markdown >}}
{{</* tabset category-name="platform" */>}}
{{</* tab name="One" category-value="one" */>}}
一
{{</* /tab */>}}
{{</* tab name="Two" category-value="two" */>}}
二
{{</* /tab */>}}
{{</* tab name="Three" category-value="three" */>}}
三
{{</* /tab */>}}
{{</* /tabset */>}}
{{< /text >}}
产生如下输出：
{{< tabset category-name="platform" >}}
{{< tab name="One" category-value="one" >}}
一
{{< /tab >}}
{{< tab name="Two" category-value="two" >}}
二
{{< /tab >}}
{{< tab name="Three" category-value="three" >}}
三
{{< /tab >}}
{{< /tabset >}}
每个选项卡的 `name` 属性包含要为该选项卡显示的文本。标签的内容几乎可以是任何常见的 markdown 格式。
可选的 `category-name` 和 `category-value` 属性允许选项卡设置在访问页面时保持粘性。当用户选择一个选项卡时，该 cookie 将自动以给定的名称和值保存。如果多个选项卡集使用相同的 cookie 名称和值，则它们的设置将在页面之间自动同步。当站点中有许多标签集具有相同类型的格式时，此功能特别有用。
例如，如果许多选项卡集用于表示 `GCP`、`BlueMix` 和 `AWS` 之间的选择，则它们都可以使用环境的 cookie 名称以及 `gcp`、`bluemix` 和 `aws` 的值。 当用户在一页中选择一个选项卡时，等效选项卡将自动在任何其他选项卡集中选择。
### 限制{#limitations}
除了以下各项，您几乎可以在标签中使用任何 markdown 语法：
- **没有标题**。选项卡中的标题将出现在目录中，但是单击目录中的条目将不会自动选择选项卡。
- **没有嵌套的标签集**。不要尝试，这太可怕了。
## 导航和表情{#banners-and-stickers}
您可以自动插入时间敏感的 banners 和 stickers 到生成的网站，来通知即将发生的事件，或宣传一些新内容。
支持两种类型的推广：
- **Countdown stickers** 显示距离重大事件发生还有多长时间 （如：“离 Istio 1.5发布还有2天”），stickers 视觉效果对用户影响最小。
- **Banners** 视觉效果最为突出，用于向用户传达即将（已经或正在）发生的重大事件 （例如，“Istio 1.5 已发布，请立即下载！” 或 “ 3 月 30 日加入我们的 KubeCon”），其呈现效果为全屏显示 。
要创建 banners 和 stickers ，您可以将文件添加到 `events/banners` 或者 `events/stickers` 目录中。 您需要为每个事件创建一个 markdown 文件。在这些文件中，使用以下特殊的字段来控制各种功能：
<table>
<thead>
<tr>
<th>字段</th>
<th>描述</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>title</code></td>
<td>事件的名称。 它未显示在网站上，仅用于诊断消息。</td>
</tr>
<tr>
<td><code>period_start</code></td>
<td> 以 <code>YYYY-MM-DD</code> 格式定义开始显示 item 的日期。
除了日期，它也可以是值 <code>latest_release</code>, 使用已知的最新 Istio 版本作为开始日期。当创建的 banner 为 "Istio x.y.z 刚刚发布" 时，此功能很有用。
</td>
</tr>
<tr>
<td><code>period_end</code></td>
<td>以 <code>YYYY-MM-DD</code> 格式定义显示 item 的最后日期。该值与 <code>period_duration</code> 互斥。
</td>
</tr>
<tr>
<td><code>period_duration</code></td>
<td>向用户显示项目的天数。 该值与上面的
<code>period_end</code> 互斥。
</td>
</tr>
<tr>
<td><code>max_impressions</code></td>
<td>在活动期间向用户显示内容的次数。 值为 3 表示在此期间用户访问的前三个页面将显示内容，并且在后续页面加载时将隐藏该内容。 值为 0 或完全省略该字段会导致该内容在此期间的所有页面访问中显示。
</td>
</tr>
<tr>
<td><code>timeout</code></td>
<td>内容在给定页面上对用户可见的时间。 经过这么长时间后，该项目将从页面中删除。</td>
</tr>
<tr>
<td><code>link</code></td>
<td>您可以指定一个URL，它将整个项目变成可点击的目标。 用户单击该项目后，该项目将不再显示给用户。 这里可以使用特殊值 `latest_release` 来引入指向当前版本的公告页面的链接。
</td>
</tr>
</tbody>
</table>
## 重命名、移动或删除页面{#renaming-moving-or-deleting-pages}
如果移动页面或将其完全删除，则应确保用户可能必须与这些页面的现有链接继续起作用。您可以通过添加别名来做到这一点，这将使用户自动从旧 URL 重定向到新 URL。
在作为重定向**目标**的页面（您希望用户登陆的页面）中，您只需在元数据中添加以下内容：
{{< text plain >}}
aliases:
- <path>
{{< /text >}}
例如
{{< text plain >}}
---
title: 经常问的问题
description: 经常问的问题。
weight: 12
aliases:
- /zh/help/faq
---
{{< /text >}}
将上述内容保存在 `faq/_index.md` 页面中后，用户将可以通过正常访问 `istio.io/faq/` 以及 `istio.io/help/faq/` 来访问该页面。
您还可以添加许多重定向，如下所示：
{{< text plain >}}
---
title: 经常问的问题
description: 经常问的问题。
weight: 12
aliases:
- /zh/faq
- /zh/faq2
- /zh/faq3
---
{{< /text >}}
## 构建和测试网站{#building-and-testing-the-site}
编辑了某些内容文件后，您将需要构建网站以测试您的更改。我们使用 [Hugo](https://gohugo.io/) 来生成我们的网站。为了在本地构建和测试站点，我们使用了包含 Hugo 的 Docker 镜像。要构建和运行该站点，只需转到根目录并执行以下操作：
{{< text bash >}}
$ make serve
{{< /text >}}
这将构建站点并启动托管该站点的 Web 服务器。然后，您可以通过 `http://localhost:1313` 连接到Web服务器。
要从远程服务器创建站点并为其提供服务，请按如下所示用服务器的 IP 地址或 DNS 域覆盖 `ISTIO_SERVE_DOMAIN`：
{{< text bash >}}
$ make ISTIO_SERVE_DOMAIN=192.168.7.105 serve
{{< /text >}}
这将构建站点并启动托管该站点的 Web 服务器。然后，您可以通过 `http://192.168.7.105:1313` 连接到 Web 服务器。
该网站的所有英文内容都位于 `content/en` 目录以及同级翻译的目录（如 `content/zh`）中。
### Linting
我们使用 [linters](https://en.wikipedia.org/wiki/Lint_(software)) 来确保网站内容的基本质量。在您将更改提交到存储库之前，这些 linter 必须运行时没有报错。linter 检查以下内容：
- HTML 校对，可确保所有链接以及其他检查均有效。
- 拼写检查。
- 样式检查，确保您的 markdown 文件符合我们的通用样式规则。
您可以使用以下命令在本地运行这些 linter 检查：
{{< text bash >}}
$ make lint
{{< /text >}}
如果您遇到拼写错误，则可以通过三种选择来解决：
- 这是一个真正的错别字，修复你的 markdown。
- 这是命令/字段/符号名称，因此请在其周围加上一些`反引号`。
- 这确实是有效的，因此请将该单词添加到存储库根目录的 .spelling 文件中。
如果由于互联网连接状况不佳而导致链接检查器出现问题，则可以为名为 `INTERNAL_ONLY` 的环境变量设置任何值，以防止 linter 检查外部链接：
{{< text bash >}}
$ make INTERNAL_ONLY=True lint
{{< /text >}}
## 使用 GitHub{#using-GitHub}
点击 [使用 GitHub 参与社区活动](/zh/about/contribute/github) 了解如何使用 GitHub 处理 Istio 文档。如果你非常感兴趣, 查看 [分支部分](/zh/about/contribute/github#branching) 来了解我们是怎么使用分支和处理冲突的。

2
content/zh/about/contribute/github/index.md
View File

@ -78,7 +78,7 @@ keywords: [contribute,community,github,pr]
1. 发布评论后，大家经过讨论一致同意合并 PR，请在文本上留下：`/hold cancel`。该命令将取消阻止 PR 合并。
## 预览工作{#previewing-your-work}
## 分支策略{#branching-strategy}
当您提交 pull request 时，您在 GitHub 上的 PR 页面会显示一个指向为您的 PR 自动构建的登入站点的链接，这对于您查看最终用户的最终页面看起来很有用。这个临时的网站，可以确保页面预览看起来正常。

104
content/zh/about/contribute/review/index.md Normal file
View File

@ -0,0 +1,104 @@
---
title: Documentation Review Process
description: Shows you how changes to the Istio documentation and website are reviewed and approved.
weight: 6
keywords: [contribute,community,github,pr,documentation,review, approval]
---
The maintainers and working group leads of the Istio Docs Working Group (WG) approve
all changes to the [Istio website](/zh/docs/).
A **documentation reviewer** is a trusted contributor that approves content that
meets the acceptance criteria described in the [review criteria](#review-criteria).
All content reviews follow the process described in [Reviewing content PRs](#review-content-prs).
Only Docs Maintainers and WG Leads can merge content into the [istio.io repository](https://github.com/istio/istio.io).
Content for Istio often needs to be reviewed on short notice and not all content
has the same relevance. The last minute nature of contributions and the finite
number of reviewers make the prioritization of content reviews necessary to
function at scale. This page provides clear review criteria to ensure all review
work happens **consistently**, **reliably** and follows the **same quality standards**.
## Review content PRs
Documentation reviewers, maintainers, and WG leads follow a clear process to
review content PRs to ensure all reviews are consistent. The process is as
follows:
1. The **Contributor** submits a new content PR to the istio.io repository.
1. The **Reviewer** performs a review of the content and determines if it meets the
acceptance criteria.
1. The **Reviewer** adds any technical WG pertinent for the content if the
contributor hasn't already.
1. The **Contributor** and the **Reviewer** work together until the content
meets all required acceptance criteria and the issues are addressed.
1. If the content is urgent and meeting the supplemental acceptance criteria
requires significant effort, the **Reviewer** files a follow up issue on
the istio.io repository to address the problems at a later date.
1. The **Contributor** addresses all required and supplemental feedback as
agreed by the Reviewer and Contributor. Any feedback filed in the follow up
issues is addressed later.
1. When a **technical** WG lead or maintainer approves the content PR, the
**Reviewer** can approve the PR.
1. If a Docs WG maintainer or lead reviewed the content, they not only approve,
but they also merge the content. Otherwise, maintainers and leads are automatically
notified of the **Reviewer's** approval and prioritize approving and merging
the already reviewed content.
The following diagram depicts the process:
{{< image width="75%" ratio="45.34%"
link="./review-process.svg"
alt="Documentation review process"
title="Documentation review process"
>}}
- **Contributors** perform the steps in the gray shapes.
- **Reviewers** perform the steps in the blue shapes.
- **Docs Maintainers and WG Leads** perform the steps in the green shapes.
## Follow up issues
When a **Reviewer** files a follow up issue as part of the
[review process](#review-content-prs), the GitHub issue must include the
following information:
- Details about the [supplemental acceptance criteria](#supplemental-acceptance-criteria)
the content failed to meet.
- Link to the original PR.
- Username of the technical Subject Matter Experts (SMEs).
- Labels to sort the issues.
- Estimate of work: Reviewers provide their best estimate of how long it would
take to address the remaining issues working alongside the original
contributor.
## Review criteria
Our review process supports our [code of conduct](https://www.contributor-covenant.org/version/2/0/code_of_conduct)
by making our review criteria transparent and applying it to all content contributions.
Criteria has two tiers: required and supplemental.
### Required acceptance criteria
- Technical accuracy: At least one technical WG lead or maintainer reviews and
approves the content.
- Correct markup: All linting and tests pass.
- Language: Content must be clear and understandable. To learn more see the
[highlights](https://developers.google.com/style/highlights) and
[general principles](https://developers.google.com/style/tone) of the Google developer
style guide.
- Links and navigation: The content has no broken links and the site builds properly.
### Supplemental acceptance criteria
- Content structure: Information structure enhances the readers' experience.
- Consistency: Content adheres to all recommendations in the
[Istio contribution guides](/zh/about/contribute/)
- Style: Content adheres to the [Google developer style guide](https://developers.google.com/style).
- Graphic assets: Diagrams follow the Istio [diagram creation guide](/zh/about/contribute/diagrams/).\
- Code samples: Content provides relevant, testable, and working code samples.
- Content reuse: Any repeatable content follows a reusability strategy using
boilerplate text.
- Glossary: New terms are added to the glossary with clear definitions.

1
content/zh/about/contribute/review/review-process.svg Normal file
View File

File diff suppressed because one or more lines are too long
Side by Side

After

Width:  |  Height:  |  Size: 6.8 KiB

4
content/zh/blog/2019/sail-the-blog/index.md
View File

@ -10,7 +10,7 @@ target_release: 1.3
欢迎来到 Istio 博客！
为了让你更方便的在我们的网站上发表博客，我们[更新了内容类型指南](/zh/about/contribute/creating-and-editing-pages/#choosing-a-page-type)。
为了让你更方便的在我们的网站上发表博客，我们[更新了内容类型指南](/zh/about/contribute/add-content/#content-types)。
这次更新的目标是对内容进行更方便的分享和搜索。
@ -22,6 +22,6 @@ target_release: 1.3
- 文章中着重介绍了 Istio 的功能。
- 文章中详细讲解了使用 Istio 完成一个任务或者满足特定用例需求的相关内容。
仅需[提交一个 PR](/zh/about/contribute/github/#how-to-contribute) 就可以发表您的博客，如果需要，可以[申请评审](/zh/about/contribute/github/#review)。
仅需[提交一个 PR](/zh/about/contribute/github/) 就可以发表您的博客，如果需要，可以[申请评审](/zh/about/contribute/review)。
我们期待能够很快就能在博客上看到你的 Istio 体验！

8
content/zh/blog/2020/_index.md Normal file
View File

@ -0,0 +1,8 @@
---
title: 2020 年的博客文章
description: 2020 年的博客文章。
weight: 8
icon: blog
decoration: dot
list_by_publishdate: true
---

2
content/zh/docs/reference/glossary/adapters.md
View File

@ -1,5 +1,5 @@
---
title: 适配器
title: Adapters
---
适配器（adapter）是 Istio [策略和遥测](/zh/docs/reference/config/policy-and-telemetry/)组件 [Mixer](#mixer) 的插件, 可使其与一组开放式基础架构后端交互，这些后端可提供核心功能，例如日志记录、监控、配额、ACL 检查等等。运行时所使用的精确的适配器集合是通过配置确定的，并可以针对新的或定制的基础架构后端轻松扩展。

2
content/zh/docs/reference/glossary/destination.md
View File

@ -1,4 +1,4 @@
---
title: 目标服务
title: Destination
---
目标服务 (destination) 是 [envoy](#envoy) 代表一个[源服务](#source) [工作负载](#workload)与之打交道的远程上游服务。这些上游服务可以有多个[服务版本](#service)，envoy 根据路由选择对应的版本。