编写新主题

本文说明了如何创建新的 Istio 文档页面。

开始之前

首先要 Fork Istio 的文档仓库，这一过程在 Working with GitHub 中有具体讲解。

选择页面类型

开始新主题之前，要清楚哪个页面类型适合你的内容：

命名主题

选择一个标题，其中包含您希望搜索引擎查找的关键字。

使用标题中的单词创建一个文件名，用连字符分隔，全部以小写字母表示。

更新 Front matter

每个文档头部都是以 Front matter 开始的。 Front matter 是文件顶部的一段 yaml 代码，上下都是用三个连字符作为间隔。下面是一段 Front matter 的示例：

---
title: <title>
description: <description>
weight: <weight>
keywords: [keyword1,keyword2,...]
---

在新的 Markdown 文件的开始处复制上述内容并更新信息字段。可用字段包括：

字段	描述
`title`	页面的简称
`description`	关于该主题内容的单行描述
`weight`	一个整数，用于确定此页面相对于同一目录中其他页面的排列顺序
`keywords`	描述页面的一系列关键字，用于创建"请参阅”链接
`draft`	如果为 true，页面不会出现在任何导航区域中
`publishdate`	博客的发布日期
`subtitle`	可选，博客的副标题，会显示在标题的下方
`attribution`	可选，博客的作者
`toc`	将其设置为 false，就不会生成目录
`force_inline_toc`	将其设置为 true 会强制将生成的目录插入到文本而不是侧边栏中

加入图片

将图像文件放在与 Markdown 文件相同的目录中。首选的图像格式是 SVG。

在 Markdown 文件中使用以下形式添加图像：

{{< image width="75%" ratio="69.52%"
    link="./myfile.svg"
    alt="当图片不可用时显示的文字"
    title="鼠标移到上方时出现的提示文字"
    caption="图片下方显示的文字"
    >}}

width、ratio、link 以及 caption 都是必要的。如果没有设置 title 的值，缺省会跟 caption 保持一致。如果没有给 alt 赋值，就会使用 title 的值，如果 title 也没有赋值，也同样会采用 caption 的值。

width 表示图像宽度相对周围文字的百分比。 ratio 必须使用（图像高度/图像宽度）* 100 手动计算。

添加图标和 emoji

您可以使用下面的方式在内容中嵌入一些常用图标：

{{< warning_icon >}}
{{< idea_icon >}}

这段代码会显示 Warning 和 Bulb

另外还可以用这种代码在内容中加入 emoji ： :``sailboat``: ，这样会显示帆船的 emoji ，就像这样 ⛵。

可用的 emoji 列表可以参看：Cheat sheet of the supported emojis。

连接到其他页面

文档中可以包含三种类型的链接，分别使用各自的方式来链接到目标内容：

**内部链接：**使用经典的 URL 语法（最好使用 HTTPS 协议）来引用 Internet 上的文件：
```
[see here](https://mysite/myfile.html)
```
**相对链接：**在网站的层次结构内，用以句号开头的相对链接引用与当前文件相同或以下级别的任何内容：
```
[see here](/zh./adir/anotherfile.html)
```
**绝对链接：**用以 / 开头的绝对链接来引用当前层次之外的内容：
```
[see here](/zh/docs/adir/afile/)
```

预格式化文本块

您可以使用 text 语法嵌入预先格式化的内容块：

{{< text plain >}}
func HelloWorld() {
  fmt.Println("Hello World")
}
{{< /text >}}

上面的代码会生成如下的输出：

func HelloWorld() {
  fmt.Println("Hello World")
}

您必须在预格式化的块中指明内容的语法。上面例子中标记的是 plain，表示不应该对块应用语法着色。同样的内容，下面改用 Go 语法进行注释：

{{< text go >}}
func HelloWorld() {
  fmt.Println("Hello World")
}
{{< /text >}}

会渲染成为：

func HelloWorld() {
  fmt.Println("Hello World")
}

可以使用 plain、markdown、yaml、json、java、javascript、c、cpp、csharp、go、html、protobuf、perl、docker 以及 bash。

控制台命令及其输出的显示

当显示一个或多个 bash 命令行时，可以使用 $ 开始：

{{< text bash >}}
$ echo "Hello"
{{< /text >}}

会渲染成为：

$ echo "Hello"

同一块中可以显示多个命令：

{{< text bash >}}
$ echo "Hello" >file.txt
$ cat file.txt
Hello
{{< /text >}}

会显示为：

$ echo "Hello" >file.txt
$ cat file.txt
Hello

还可以使用分行命令：

{{< text bash >}}
$ echo "Hello" \
    >file.txt
$ echo "There" >>file.txt
$ cat file.txt
Hello
There
{{< /text >}}

会显示为：

$ echo "Hello" \
    >file.txt
$ echo "There" >>file.txt
$ cat file.txt
Hello
There

默认情况下，输出部分使用 plain 语法进行处理。如果输出使用众所周知的语法，您可以指定它并为其着色。这对于 yaml 或 json 输出尤为常见：

{{< 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 >}}

会呈现为:

$ 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"}

对 Istio GitHub 文件的引用

如果您的代码块引用了 Istio 的 GitHub repo 中的文件，则可以用一对 @ 包围文件的相对路径名，这样路径就会被渲染为为从当前分支到文件的链接。例如：

{{< text bash >}}
$ istioctl create -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
{{< /text >}}

上面代码的渲染结果：

$ istioctl create -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@

展示文件片段

这个功能用于显示较大文件的一部分内容。可以在文件中使用 $ snippet 和 $ endsnippet 注释来创建片段。例如，您可以使用如下所示的文本文件：

BEFORE

# $snippet SNIP1
This is snippet 1
# $endsnippet

# $snippet SNIP2
This is snippet 2
# $endsnippet

AFTER

Markdown 文件中可以这样对片段进行引用：

{{< text_file file="examples/snippet_example.txt" syntax="plain" snippet="SNIP1" >}}

file 指定了文本文件在文档库中的相对路径；syntax 指定了用于着色的语法 (普通文本可以使用 plain)； snippet 就是片段的名称。如果省略了 snippet，就会把整个文件包含进来。

上面代码的输出如下：

This is snippet 1

一个常见的事情是就将示例脚本或 yaml 文件从 GitHub 复制到文档仓库中，然后在文件中使用代码片段来生成文档中的示例。要从 GitHub 中提取带注释的文件，请在文档仓库中脚本 scripts/grab_reference_docs.sh 末尾添加所需的条目。

展示动态内容

您可以拉入外部文件并将其内容显示为预格式化文本块。可以很方便的显示配置文件或测试文件。使用如下语句就能完成这一任务：

{{< text_dynamic url="https://raw.githubusercontent.com/istio/istio/master/samples/bookinfo/kube/mixer-rule-ratings-ratelimit.yaml" syntax="yaml" >}}

会输出这样的内容：

如果文件来自不同的原始站点，则应在该站点上启用 CORS。请注意 GitHub（raw.githubusercontent.com）原始内容网站是可以使用的。

引用 GitHub 文件

从 Istio 的 GitHub 仓库引用文件时，最好引用仓库中的特定分支。要引用文档网站当前定位的特定分支，请使用注解 {{< branch_name >}}。例如：

See this [source file](https://github.com/istio/istio/blob/{{< branch_name >}}/mixer/cmd/mixs/cmd/server.go)/

页面的移动或重命名

如果想要移动页面并希望确保现有链接继续有效，可以使用重定向指令来达成目标。

在作为重定向目标的页面（您希望用户登陆的页面）中，您只需将以下内容添加到 Front Matter：

aliases:
    - <url>

例如：

---
title: Frequently Asked Questions
description: Questions Asked Frequently.
weight: 12
aliases:
    - /faq
---

上面的页面保存为 _help/faq.md，用户不管使用 istio.io/help/faq/ 还是 istio.io/faq/，都能到达这一页面。

还可以加入多个重定向指令：

---
title: Frequently Asked Questions
description: Questions Asked Frequently.
weight: 12
aliases:
    - /faq
    - /faq2
    - /faq3
---

注意事项

在为 istio.io 写内容时，的确会有一些复杂。您需要了解这些内容才能让网站基础架构正确处理您的内容：

确保代码块总是以4个空格的倍数缩进。否则，渲染页面中代码块的缩进将关闭，并且代码块中会插入空格，导致剪切和粘贴不能正常工作。
确保所有图像具有有效的宽度和宽高比。否则会根据屏幕进行奇怪的渲染。
在代码块中插入链接时候，如果使用 @@ 进行注解，那么这个链接就不会被检查。这样就可以把坏链接放进内容之中，并且不会被工具阻止了，建议慎重使用。