添加代码块
Istio 文档中的代码块是嵌入式预定义格式的内容块。我们使用 Hugo 构建网站,并使用
text
和 text_import
短代码将代码添加到页面中。
这样我们可以为读者提供更好的体验。渲染的代码块可以轻松地复制,打印或下载。
所有的贡献内容都必须使用这些短代码。如果您的内容未使用适当的短代码,则它不会被合并, 直到做出适当的修改。该页面包含嵌入式代码块的几个示例以及可用的格式化选项。
代码块的最常见示例是命令行界面(CLI)命令/指令,例如:
{{< text bash >}}
$ echo "Hello"
{{< /text >}}
短代码要求您的每个 CLI 命令都以 $
开头,其渲染结果如下所示:
$ echo "Hello"
您可以在一个代码块中使用多个命令,但是短代码只能识别单个输出,例如:
{{< text bash >}}
$ echo "Hello" >file.txt
$ cat file.txt
Hello
{{< /text >}}
默认情况下,会给定并设置属性为 bash
,这些命令将使用 bash 语法高亮显示,
并且输出将显示为纯文本,例如:
$ echo "Hello" >file.txt
$ cat file.txt
Hello
为了便于阅读,您可以使用 \
在新的一行上继续长命令,新行必须缩进,例如:
{{< text bash >}}
$ echo "Hello" \
>file.txt
$ echo "There" >>file.txt
$ cat file.txt
Hello
There
{{< /text >}}
Hugo 可以渲染续行命令:
$ echo "Hello" \
>file.txt
$ echo "There" >>file.txt
$ cat file.txt
Hello
There
您的 workload 可以用各种编程语言编码。 因此,我们实现了多种对代码块中语法高亮显示的支持。
添加语法高亮
让我们从下面的 “Hello World” 例子开始:
{{< text plain >}}
func HelloWorld() {
fmt.Println("Hello World")
}
{{< /text >}}
plain
属性没有对代码进行语法高亮渲染:
func HelloWorld() {
fmt.Println("Hello World")
}
您可以为代码块中的内容指定语言,以实现语法高亮。上面的例子指定了语法为 plain
,
所有代码块的渲染结果没有任何语法高亮。但是,您可以指定其语法为 Go
,例如:
{{< text go >}}
func HelloWorld() {
fmt.Println("Hello World")
}
{{< /text >}}
然后,Hugo 会添加适当的语法高亮:
func HelloWorld() {
fmt.Println("Hello World")
}
支持的语法
Istio 代码块目前支持下面这些语言的语法高亮:
plain
markdown
yaml
json
java
javascript
c
cpp
csharp
go
html
protobuf
perl
docker
bash
默认情况下,CLI 命名的输出结果会按照 plain 文本进行渲染,即没有语法高亮。 如果您想为输出添加语法高亮,您可以在短代码中指定语法。在 Istio 中,最常见的例子就是 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 >}}
根据 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_import
短代码从文件中导入内容或代码。该文件可以存储在文档存储库中,也可以存储在允许跨域访问(CORS)的外部源中。
从 istio.io
仓库中的文件导入代码
使用 file
属性,从 Istio 文档仓库中的一个文件中导入内容,例如:
{{< text_import file="test/snippet_example.txt" syntax="plain" >}}
上面的例子会将文件的内容渲染为存文本:
BEFORE
# $snippet SNIP1
This is chunk 1
on two lines
# $endsnippet
# $snippet SNIP2
This is chunk 2
# $endsnippet
# $snippet SNIP3
This is chunk 3
# $endsnippet
AFTER
通过设置 syntax=
字段的值,指定内容的语言,可以获得语法高亮的渲染。
通过 URL 从外部资源导入代码
类似的,您可以从互联网动态的导入内容。使用 url
属性指定资源。
下面的例子导入了同一个文件,但它是通过 URL 导入的:
{{< text_import url="https://raw.githubusercontent.com/istio/istio.io/master/test/snippet_example.txt" syntax="plain" >}}
如您所见,渲染结果跟前面的完全相同:
如果文件来自其它网站,请确保目标网站允许跨域访问(CORS)。注意,这里可以使用
GitHub 原始网站(raw.githubusercontent.com
)的内容。
从较大的文件导入代码片段
有时候,您不需要一个文件的全部内容。此时,您可以使用 named snippets
来控制要渲染该文件的哪一部分。用包含 $snippet SNIPPET_NAME
和 $endsnippet
标签的注释标记代码片段中所需的代码。两个标签之间的内容表示要渲染代码片段。例如,获取以下文件:
BEFORE
# $snippet SNIP1
This is chunk 1
on two lines
# $endsnippet
# $snippet SNIP2
This is chunk 2
# $endsnippet
# $snippet SNIP3
This is chunk 3
# $endsnippet
AFTER
该文件具有三个单独的代码段:SNIP1
、SNIP2
和 SNIP3
。约定是使用全大写字母的名称。
要引用文档中的特定代码段,请将短代码中 snippet 属性的值设置为代码段的名称,例如:
{{< text_import file="test/snippet_example.txt" syntax="plain" snippet="SNIP1" >}}
这样代码块的渲染结果将仅包含 SNIP1
代码片段的内容:
This is chunk 1
on two lines
您还可以使用 text_import
短代码的 syntax
属性为代码片段指定语法高亮。
对于包含 CLI 命令的代码片段,您可以使用 outputis
属性为输出结果指定语法高亮。
链接 GitHub 上的文件
有些代码块需要引用 Istio 的 GitHub 仓库中的文件。
其中最常见的情况就是引用 YAML 配置文件。无需将 YAML 文件的全部内容复制到您的代码块中,
您可以使用 @
符号将文件的相对路径名括起来。此标记会将路径渲染为指向 GitHub
中当前发行版本分支的文件的链接,例如:
{{< text bash >}}
$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
{{< /text >}}
该路径会渲染为一个链接,可将您带到相应的文件:
$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
默认情况下,这些链接指向 istio/istio
存储库当前发行版的分支。想要让链接指向另一个
Istio 仓库,可以使用 repo
属性,例如:
{{< text syntax="bash" repo="api" >}}
$ cat @README.md@
{{< /text >}}
该路径将渲染为指向 istio/api
仓库的 README.md
文件的链接:
$ cat @README.md@
有时,您的代码块会将 @
留作它用。您可以使用 expandlinks
属性打开和关闭链接扩展,例如:
{{< text syntax="bash" expandlinks="false" >}}
$ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
{{< /text >}}
高级功能
要使用更多下面介绍到的用于预定义格式内容的高级功能,请使用 text
序列的扩展形式,
而不是到前面介绍和展示的简化形式。展开的表单会使用标准的 HTML 属性:
{{< 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 >}}
可用的属性有:
属性 | 描述 |
---|---|
file | 在代码块中显示的文件的路径。 |
url | 在代码块中显示的文档的 URL。 |
syntax | 代码块的语法。 |
outputis | 当语法为 bash 时,该属性指定命令输出结果的语法。 |
downloadas | 当用户下载该代码块时默认的文件名。 |
expandlinks | 是否在代码块中为 GitHub 文件引用开启链接扩展。 |
snippet | 要从代码块中提取的内容的 snippet 名称。 |
repo | 嵌入代码块中的仓库的 GitHub 链接。 |
下载名
您可以使用 downloadas
属性定义当某人下载代码块时默认的文件名,例如:
{{< text syntax="go" downloadas="hello.go" >}}
func HelloWorld() {
fmt.Println("Hello World")
}
{{< /text >}}
如果您未指定下载的文件名,则 Hugo 会根据以下可用名称之一自动导出一个:
- 对于内联内容,使用的当前页面的标题
- 导入代码的源文件的名称
- 导入代码的源的 URL