コードブロックの追加

 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

ファイルが異なるオリジンサイトからのものである場合、CORSはそのサイトで有効にする必要があります。GitHubのrawコンテンツサイト（raw.githubusercontent.com）はここで使用できることに注意してください。

大きなファイルからコードスニペットをインポートする

場合によっては、ファイル全体の内容が必要ないことがあります。名前付きスニペットを使用して、レンダリングするコンテンツの部分を制御できます。スニペットに含めたいコードに、$snippet SNIPPET_NAMEおよび$endsnippetタグを含むコメントでタグ付けします。2つのタグの間のコンテンツがスニペットを表します。例えば、次のファイルを見てみましょう。

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の3つの個別のスニペットがあります。規約では、すべて大文字を使用してスニペットに名前を付けます。ドキュメント内の特定のスニペットを参照するには、ショートコードの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
この情報は役に立ちましたか？
改善のためのご提案はありますか？

フィードバックありがとうございます！