添加代码块

 7 分钟阅读  

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

您的 工作负载 可以使用各种编程语言进行编码。因此，我们在代码块中实现了对多种语法高亮组合的支持。

添加语法高亮

让我们从以下“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 命令的输出被视为纯文本，并在没有语法高亮的情况下渲染。如果您需要向输出添加语法高亮，您可以在短代码中指定语言。在 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" >}}

如您所见，内容以与之前相同的方式渲染

Zip
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

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

从大型文件中导入代码片段

有时，您不需要整个文件的内容。您可以使用命名代码段控制要渲染的内容的哪些部分。使用包含 $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 属性指定输出的语法。

某些代码块需要引用来自 Istio 的 GitHub 存储库 的文件。最常见的示例是引用 YAML 配置文件。与其将 YAML 文件的整个内容复制到代码块中，不如用 @ 符号包围文件的相对路径名。此标记会将路径渲染为指向 GitHub 中当前发布分支中的文件的链接，例如

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

路径会渲染为一个链接，将您带到相应的文件

Zip
$ kubectl apply -f samples/bookinfo/networking/virtual-service-reviews-v3.yaml

默认情况下，这些链接指向 istio/istio 存储库的当前发布分支。要使链接指向其他 Istio 存储库，可以使用 repo 属性，例如

Zip
{{< text syntax="bash" repo="api" >}}
$ cat @README.md@
{{< /text >}}

路径会渲染为指向 istio/api 存储库的 README.md 文件的链接

Zip
$ cat README.md

有时，您的代码块会将 @ 用于其他用途。可以使用 expandlinks 属性打开和关闭链接扩展，例如

Zip
{{< 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要从预格式化块中提取的内容 代码段 的名称。
repo用于 GitHub 链接 的存储库，嵌入在预格式化块中。

下载名称

您可以使用 downloadas 属性定义有人选择下载代码块时使用的名称，例如

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

如果您没有指定下载名称，Hugo 会根据以下可用可能名称之一自动推断一个名称

  • 内联内容的当前页面的标题
  • 包含导入代码的文件的名称
  • 导入代码源的 URL
这些信息有用吗？
您对改进有什么建议吗？

感谢您的反馈！