加入程式碼區塊

 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

您的 工作負載 (workloads) 可以用各種程式語言編寫。因此，我們實作了對程式碼區塊中多種語法高亮組合的支援。

加入語法醒目顯示

讓我們從以下「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 命令的輸出會被視為純文字，並以不帶語法高亮的方式呈現。如果您需要為輸出新增語法高亮，您可以在 shortcode 中指定語言。在 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 shortcode 從檔案匯入內容或程式碼。該檔案可以儲存在文件儲存庫中，或儲存在已啟用跨來源資源共享 (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)

如果檔案來自不同的來源網站，則應在該網站上啟用 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。慣例是使用全部大寫字母命名程式碼片段。若要在文件中引用特定的程式碼片段，請將 shortcode 中的 snippet 屬性值設定為程式碼片段的名稱，例如

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

產生的程式碼區塊僅包含 SNIP1 程式碼片段的程式碼

This is chunk 1
on two lines

您可以使用 text_import shortcode 的 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
此資訊是否有用？
您是否有任何改進建議？

感謝您的回饋！