ショートコードの使用

Hugoのショートコードは、特定の構文を持つ特別なプレースホルダーであり、タブ、画像、アイコン、他のページへのリンク、特別なコンテンツレイアウトなど、動的なコンテンツエクスペリエンスを作成するためにコンテンツに追加できます。

このページでは、利用可能なショートコードと、コンテンツでの使用方法について説明します。

画像の追加

画像ファイルは、使用するmarkdownファイルと同じディレクトリに配置します。ローカライゼーションを容易にし、アクセシビリティを向上させるために、推奨される画像形式はSVGです。次の例は、画像を追加するために必要な必須フィールドを持つショートコードを示しています。

{{< image width="75%" ratio="45.34%"
    link="./<image.svg>"
    caption="<The caption displayed under the image>"
    >}}

linkフィールドとcaptionフィールドは必須ですが、このショートコードはオプションのフィールドもサポートしています。例えば、以下のようなものです。

{{< image width="75%" ratio="45.34%"
    link="./<image.svg>"
    alt="<Alternate text used by screen readers and when loading the image fails>"
    title="<Text that appears on mouse-over>"
    caption="<The caption displayed under the image>"
    >}}

titleフィールドを含めない場合、Hugoはcaptionで設定されたテキストを使用します。altフィールドを含めない場合、Hugoはtitleのテキストを使用します。また、titleが定義されていない場合は、captionのテキストを使用します。

widthフィールドは、周囲のテキストに対する画像のサイズを設定し、デフォルトは100％です。

ratioフィールドは、画像の幅に対する高さを設定します。Hugoは、フォルダ内の画像ファイルについてこの値を自動的に計算します。ただし、外部画像については手動で計算する必要があります。ratioの値を([画像高さ] / [画像幅]) * 100に設定します。

アイコンの追加

次のコンテンツを使用して、一般的なアイコンをコンテンツに埋め込むことができます。

{{< warning_icon >}}
{{< idea_icon >}}
{{< checkmark_icon >}}
{{< cancel_icon >}}
{{< tip_icon >}}

アイコンはテキスト内にレンダリングされます。例えば, , , そして.

他のページへのリンクの追加

Istioドキュメントでは、ターゲットに応じて3種類のリンクをサポートしています。各タイプは、ターゲットを表現するために異なる構文を使用します。

• 外部リンク。これらは、IstioドキュメントまたはIstio GitHubリポジトリの外部にあるページへのリンクです。URLを含めるには、標準のMarkdown構文を使用します。インターネット上のファイルを参照する場合は、HTTPSプロトコルを使用します。例えば

  [Descriptive text for the link](https://mysite/myfile.html)
  

• 相対リンク。これらのリンクは、現在のファイルと同じレベルまたは階層の下位にあるページをターゲットにします。相対リンクのパスはピリオド.で始めます。例えば

  [This links to a sibling or child page](./sub-dir/child-page.html)
  

• 絶対リンク。これらのリンクは、現在のページの階層外にあるが、Istio Webサイト内にあるページをターゲットにします。絶対リンクのパスはスラッシュ/で始めます。例えば

  [This links to a page on the about section](/about/page/)
  

タイプに関係なく、リンクはコンテンツを含むindex.mdファイルではなく、それを含むフォルダを指します。

GitHub上のコンテンツへのリンクの追加

GitHub上のコンテンツまたはファイルを参照する方法はいくつかあります。

• {{< github_file >}}は、yamlファイルなど、GitHub内の個々のファイルを参照する方法です。このショートコードは、https://raw.githubusercontent.com/istio/istio*へのリンクを生成します。例えば

  [liveness]({{< github_file >}}/samples/health-check/liveness-command.yaml)
  

• {{< github_tree >}}は、GitHub内のディレクトリツリーを参照する方法です。このショートコードは、https://github.com/istio/istio/tree*へのリンクを生成します。例えば

  [httpbin]({{< github_tree >}}/samples/httpbin)
  

• {{< github_blob >}}は、GitHubソース内のファイルを参照する方法です。このショートコードは、https://github.com/istio/istio/blob*へのリンクを生成します。例えば

  [RawVM MySQL]({{< github_blob >}}/samples/rawvm/README.md)
  

上記のショートコードは、ドキュメントが現在ターゲットにしているブランチに基づいて、GitHubの適切なブランチへのリンクを生成します。現在どのブランチがターゲットになっているかを確認するには、{{< source_branch_name >}}ショートコードを使用して、現在ターゲットにされているブランチの名前を取得できます。

バージョン情報

Webサイトから現在のバージョンを取得して、コンテンツに現在のIstioバージョンを表示するには、次のショートコードを使用します。

• {{< istio_version >}}、これは1.24としてレンダリングされます
• {{< istio_full_version >}}、これは1.24.0としてレンダリングされます

用語集の用語

ページで特殊なIstio用語を紹介する場合、貢献に関する補足的な承認基準では、その用語を用語集に含め、{{< gloss >}}ショートコードを使用して最初のインスタンスをマークアップする必要があります。このショートコードは、読者が用語をクリックして定義を示すポップアップを表示するように促す特別なレンダリングを生成します。例えば

The Istio component that programs the {{<gloss>}}Envoy{{</gloss>}} proxies, responsible for service discovery, load balancing, and routing.

次のようにレンダリングされます

サービスディスカバリー、ロードバランシング、ルーティングを担当する、EnvoyプロキシをプログラムするIstioコンポーネント。

テキストで用語のバリアントを使用する場合は、このショートコードを使用して定義付きのポップアップを含めることもできます。置換を指定するには、ショートコード内に用語集のエントリを含めるだけです。例えば

{{<gloss envoy>}}Envoy's{{</gloss>}} HTTP support was designed to first and foremost be an HTTP/2 multiplexing proxy.

envoyの用語集エントリのポップアップと共に次のようにレンダリングされます。

EnvoyのHTTPサポートは、まず第一にHTTP/2多重化プロキシとして設計されました。

コールアウト

コンテンツのブロックを強調するには、警告、アイデア、ヒント、または引用としてフォーマットできます。すべてのコールアウトは非常に似たショートコードを使用します。

{{< warning >}}
This is an important warning
{{< /warning >}}

{{< idea >}}
This is a great idea
{{< /idea >}}

{{< tip >}}
This is a useful tip from an expert
{{< /tip >}}

{{< quote >}}
This is a quote from somewhere
{{< /quote >}}

上記のショートコードは次のようにレンダリングされます

コールアウトは控えめに使用してください。各タイプのコールアウトには特定の目的があり、それらを過度に使用すると、意図された目的とその有効性が損なわれます。一般的に、コンテンツファイルごとに複数のコールアウトを含めるべきではありません。

定型文の使用

コンテンツの単一ソースを維持しながら再利用するには、定型文ショートコードを使用します。定型文をコンテンツファイルに埋め込むには、次のようにboilerplateショートコードを使用します。

{{< boilerplate example >}}

上記のショートコードには、/content/en/boilerplates/フォルダのexample.md Markdownファイルから次のコンテンツが含まれます

これは定型文のmarkdown テキストです。

A sample nested text block in a boilerplate.

この例は、現在の場所に挿入したいコンテンツを含むMarkdownファイルのファイル名を含める必要があることを示しています。既存の定型文ファイルは、/content/en/boilerplatesディレクトリにあります。

タブの使用

複数のオプションまたはフォーマットを持つコンテンツを表示するには、タブセットとタブを使用します。例えば

• 異なるプラットフォームに対応する同等のコマンド
• 異なる言語での同等のコードサンプル
• 代替構成

タブ付きコンテンツを挿入するには、tabsetおよびtabsショートコードを組み合わせて使用します。例えば

{{< tabset category-name="platform" >}}

{{< tab name="One" category-value="one" >}}
ONE
{{< /tab >}}

{{< tab name="Two" category-value="two" >}}
TWO
{{< /tab >}}

{{< tab name="Three" category-value="three" >}}
THREE
{{< /tab >}}

{{< /tabset >}}

上記のショートコードは次の出力を生成します

各タブのname属性の値には、タブに表示されるテキストが含まれます。各タブ内には、通常のMarkdownコンテンツを含めることができますが、タブには制限事項があります。

category-nameおよびcategory-value属性はオプションであり、選択したタブがページへのアクセス全体で固定されるようにします。例えば、訪問者がタブを選択すると、その選択は指定された名前と値で自動的に保存されます。複数のタブセットが同じカテゴリ名と値を使用する場合、それらの選択はページ間で自動的に同期されます。これは、サイトに同じタイプのフォーマットを保持する多くのタブセットがある場合に特に役立ちます。

例えば、複数のタブセットでGCP、BlueMix、およびAWSのオプションを提供できます。category-name属性の値をenvironmentに設定し、category-value属性の値をgcp、bluemix、およびawsに設定できます。次に、読者が1つのページでタブを選択すると、その選択はWebサイト全体のすべてのタブセットで自動的に引き継がれます。

タブの制限

次の例外を除き、タブではほとんどすべてのMarkdownを使用できます。

• ヘッダー。タブ内のヘッダーは目次に表示されますが、目次のリンクをクリックしても、タブが自動的に選択されるわけではありません。

• ネストされたタブセット。タブセットをネストしないでください。そうすると、読書体験が非常に悪くなり、重大な混乱を引き起こす可能性があります。

バナーとステッカーの使用

今後のイベントを宣伝したり、新しいものを公表したりするために、生成されたサイトに、時間制限付きのバナーとステッカーを自動的に挿入することができます。プロモーションのために、次のショートコードを実装しました。

• カウントダウンステッカー：大きなイベントまでの残り時間を表示します。例えば、「3月30日のServiceMeshConまであと37日」など。ステッカーはイベント前に読者に視覚的なインパクトを与えるため、控えめに使用する必要があります。

• バナー：これから開催される、開催中の、または開催された重大なイベントについて、読者に目立つメッセージを表示します。例えば、「Istio 1.5がリリースされました。今すぐダウンロードしてください！」または「3月30日のServiceMeshConにご参加ください」など。バナーは、イベント期間中に読者に表示されるフルスクリーンのスライスです。

バナーとステッカーを作成するには、events/bannersまたはevents/stickersフォルダにMarkdownファイルを作成します。動作を制御するための専用のフロントマターフィールドを使用して、イベントごとに1つのMarkdownファイルを作成します。次の表で、利用可能なオプションについて説明します。