添加代码块

    这样我们可以为读者提供更好的体验。渲染的代码块可以轻松地复制，打印或下载。

    所有的贡献内容都必须使用这些短代码。如果您的内容未使用适当的短代码，则它不会被合并，直到做出适当的修改。该页面包含嵌入式代码块的几个示例以及可用的格式化选项。

    代码块的最常见示例是命令行界面（CLI）命令/指令，例如：

    短代码要求您的每个 CLI 命令都以 $ 开头，其渲染结果如下所示：

    1. $ echo "Hello"

    您可以在一个代码块中使用多个命令，但是短代码只能识别单个输出，例如：

    1. {{< text bash >}}
    2. $ echo "Hello" >file.txt
    3. $ cat file.txt
    4. Hello
    5. {{< /text >}}

    默认情况下，会给定并设置属性为 bash，这些命令将使用 bash 语法高亮显示，并且输出将显示为纯文本，例如：

    1. $ echo "Hello" >file.txt
    2. $ cat file.txt
    3. Hello

    为了便于阅读，您可以使用 \ 在新的一行上继续长命令，例如：

    1. {{< text bash >}}
    2. $ echo "Hello" \
    3.     >file.txt
    4. $ echo "There" >>file.txt
    5. $ cat file.txt
    6. Hello
    7. There
    8. {{< /text >}}

    Hugo 可以渲染续行命令：

    1. $ echo "Hello" \
    2.     >file.txt
    3. $ echo "There" >>file.txt
    4. $ cat file.txt
    5. Hello
    6. There

    您的 workload 可以用各种编程语言编码。因此，我们实现了多种对代码块中语法高亮显示的支持。

    让我们从下面的 “Hello World” 例子开始：

    1. {{< text plain >}}
    2. func HelloWorld() {
    3.   fmt.Println("Hello World")
    4. }
    5. {{< /text >}}

    plain 属性没有对代码进行语法高亮渲染：

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

    你可以为代码块中的内容指定语言，以实现语法高亮。上面的例子指定了语法为 plain，所有代码块的渲染结果没有任何语法高亮。但是，你可以指定其语法为 Go，例如：

    然后，Hugo 会添加适当的语法高亮：

    1. func HelloWorld() {
    2.   fmt.Println("Hello World")
    • plain
    • markdown
    • yaml
    • json
    • java
    • javascript
    • c
    • cpp
    • csharp
    • go
    • protobuf
    • perl
    • docker
    • bash

    默认情况下，CLI 命名的输出结果会按照 plain 文本进行渲染，即没有语法高亮。如果你想为输出添加语法高亮，你可以在短代码中指定语法。在 Istio 中，最常见的例子就是 YAML 和 JSON 的输出结果，例如：

    1. {{< text bash json >}}
    2. $ 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\"
    3. {"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"}
    4. {"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"}
    5. {"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"}
    6. {"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"}
    7. {"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"}
    8. {{< /text >}}

    根据 bash 语法高亮显示命令，并根据 JSON 语法高亮显示结果。

    1. $ 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\"
    2. {"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"}
    3. {"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"}
    4. {"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"}
    5. {"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"}
    6. {"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）的外部源中。

    使用 file 属性，从 Istio 文档仓库中的一个文件中导入内容，例如：

    1. {{< text_import file="test/snippet_example.txt" syntax="plain" >}}

    上面的例子会将文件的内容渲染为存文本：

    1. BEFORE
    3. # $snippet SNIP1
    4. This is chunk 1
    5. on two lines
    6. # $endsnippet
    8. # $snippet SNIP2
    9. This is chunk 2
    10. # $endsnippet
    12. # $snippet SNIP3
    13. # $endsnippet
    15. AFTER

    通过设置 syntax= 字段的值，指定内容的语言，可以获得语法高亮的渲染。

    类似的，你可以从互联网动态的导入内容。使用 url 属性指定资源。下面的例子导入了同一个文件，但它是通过 URL 导入的：

    1. {{< 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 标签的注释标记代码片段中所需的代码。两个标签之间的内容表示要渲染代码片段。例如，获取以下文件：

    1. BEFORE
    3. # $snippet SNIP1
    4. This is chunk 1
    5. on two lines
    6. # $endsnippet
    8. # $snippet SNIP2
    10. # $endsnippet
    12. # $snippet SNIP3
    13. This is chunk 3
    14. # $endsnippet
    16. AFTER

    该文件具有三个单独的代码段：SNIP1、SNIP2 和 SNIP3。约定是使用全大写字母的名称。要引用文档中的特定代码段，请将短代码中 snippet 属性的值设置为代码段的名称，例如：

    这样代码块的渲染结果将仅包含 SNIP1 代码片段的内容：

    1. This is chunk 1
    2. on two lines

    有些代码块需要引用 Istio 的 GitHub 仓库中的文件。其中最常见的情况就是引用 YAML 配置文件。无需将 YAML 文件的全部内容复制到您的代码块中，您可以使用 @ 符号将文件的相对路径名括起来。此标记会将路径渲染为指向 GitHub 中当前发行版本分支的文件的链接，例如：

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

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

    Zip

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

    默认情况下，这些链接指向 istio/istio 存储库当前发行版的分支。想要让链接指向另一个 Istio 仓库，可以使用 repo 属性，例如：

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

    该路径将渲染为指向 istio/api 仓库的 README.md 文件的链接：

    Zip

    1. $ cat @README.md@

    有时，您的代码块会将 @ 留作它用。您可以使用 expandlinks 属性打开和关闭链接扩展，例如：

    1. {{< text syntax="bash" expandlinks="false" >}}
    2. $ kubectl apply -f @samples/bookinfo/networking/virtual-service-reviews-v3.yaml@
    3. {{< /text >}}

    要使用更多下面介绍到的用于预定义格式内容的高级功能，请使用 text 序列的扩展形式，而不是到前面介绍和展示的简化形式。展开的表单会使用标准的 HTML 属性：

    1. {{< text syntax="bash" outputis="json" >}}
    2. $ 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\"
    3. {"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"}
    4. {"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"}
    5. {"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"}
    6. {"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"}
    7. {"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"}
    8. {{< /text >}}

    可用的属性有：

    您可以使用 downloadas 属性定义当某人下载代码块时默认的文件名，例如：

    • 对于内联内容，使用的当前页面的标题
    • 导入代码的源的 URL