ドキュメントスタイルの概要

• 1: ドキュメントコンテンツガイド
• 2: コンテンツの構造化
• 3: カスタムHugoショートコード

1 - ドキュメントコンテンツガイド

このページでは、Kubernetesのドキュメント上のコンテンツのガイドラインを説明します。

許可されるコンテンツに関して疑問がある場合は、Kubernetes Slackの#sig-docsチャンネルに参加して質問してください！

Kubernetes Slackには、https://slack.k8s.io/ から参加登録ができます。

Kubernetesドキュメントの新しいコンテンツの作成に関する情報については、スタイルガイドに従ってください。

概要

ドキュメントを含むKubernetesのウェブサイトのソースは、kubernetes/websiteリポジトリに置かれています。

Kubernetesの主要なドキュメントはkubernetes/website/content/<language_code>/docsフォルダに置かれており、これらはKubernetesプロジェクトを対象としています。

許可されるコンテンツ

Kubernetesのドキュメントにサードパーティーのコンテンツを掲載することが許されるのは、次の場合のみです。

• コンテンツがKubernetesプロジェクト内のソフトウェアのドキュメントとなる場合
• コンテンツがプロジェクト外のソフトウェアのドキュメントとなるが、Kubernetesを機能させるために必要である場合
• コンテンツがkubernetes.ioの正規のコンテンツであるか、他の場所の正規のコンテンツへのリンクである場合

サードパーティーのコンテンツ

Kubernetesのドキュメントには、Kubernetesプロジェクト(kubernetesおよびkubernetes-sigs GitHub organizationsに存在するプロジェクト)の適用例が含まれています。

Kubernetesプロジェクト内のアクティブなコンテンツへのリンクは常に許可されます。

Kubernetesを機能させるためには、一部サードパーティーのコンテンツが必要です。たとえば、コンテナランタイム(containerd、CRI-O、Docker)、ネットワークポリシー(CNI plugin)、Ingressコントローラー、ロギングなどです。

ドキュメント内で、Kubernetesプロジェクト外のサードパーティーのオープンソースソフトウェア(OSS)にリンクすることができるのは、Kubernetesを機能させるために必要な場合のみです。

情報源が重複するコンテンツ

可能な限り、Kubernetesのドキュメントは正規の情報源にリンクするようにし、情報源が重複してしまうようなホスティングは行いません。

情報源が重複したコンテンツは、メンテナンスするために2倍の労力(あるいはそれ以上！)が必要になり、より早く情報が古くなってしまいます。

その他の情報

許可されるコンテンツに関して疑問がある場合は、Kubernetes Slackの#sig-docsチャンネルに参加して質問してください！

次の項目

• スタイルガイドを読む

2 - コンテンツの構造化

このサイトではHugoを使用しています。Hugoでは、コンテンツの構造化がコアコンセプトとなっています。

ページの一覧

ページの順序

ドキュメントのサイドメニューやページブラウザーなどでは、Hugoのデフォルトのソート順序を使用して一覧を作成しています。デフォルトでは、weight(1から開始)、日付(最新のものが1番目)、最後にリンクのタイトルの順でソートされます。

そのため、特定のページやセッションを上に移動したい場合には、ページのフロントマター内のweightを設定します。

title: My Page
weight: 10

ドキュメントのメインメニュー

ドキュメントのメインメニューは、docs/以下に置かれたセクションのコンテンツファイル_index.mdのフロントマター内にmain_menuフラグが設定されたものから生成されます。

main_menu: true

リンクのタイトルは、ページのlinkTitleから取得されることに注意してください。そのため、ページのタイトルとは異なるリンクテキストにしたい場合、コンテンツファイル内の値を以下のように設定します。

main_menu: true
title: ページタイトル
linkTitle: リンク内で使われるタイトル

ドキュメントのサイドメニュー

ドキュメントのサイドバーメニューは、docs/以下の現在のセクションツリーから生成されます。

セクションと、そのセクション内のページがすべて表示されます。

特定のセクションやページをリストに表示したくない場合、フロントマター内のtoc_hideフラグをtrueに設定してください。

toc_hide: true

コンテンツが存在するセクションに移動すると、特定のセクションまたはページ(例:index.md)が表示されます。それ以外の場合、そのセクションの最初のページが表示されます。

ドキュメントのブラウザー

ドキュメントのホームページのページブラウザーは、docsセクション直下のすべてのセクションとページを使用して生成されています。

特定のセクションやページを表示したくない場合、フロントマターのtoc_hideフラグをtrueに設定してください。

toc_hide: true

メインメニュー

右上のメニュー(およびフッター)にあるサイトリンクは、page-lookupの機能を使用して実装されています。これにより、ページが実際に存在することを保証しています。そのため、たとえばcase-studiesのセクションが特定の言語のサイトに存在しない場合、メニューにはケーススタディのリンクが表示されません。

Page Bundle

スタンドアローンのコンテンツページ(Markdownファイル)に加えて、Hugoでは、Page Bundlesがサポートされています。

Page Bundleの1つの例は、カスタムのHugo Shortcodeです。これは、leaf bundleであると見做されます。ディレクトリ内のすべてのファイルは、index.mdを含めてバンドルの一部となります。これには、ページからの相対リンク、処理可能な画像なども含まれます。

en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json

もう1つのPage Bundleがよく使われる例は、includesバンドルです。フロントマターにheadless: trueを設定すると、自分自身のURLを持たなくなり、他のページ内でのみ使用されるようになります。

en/includes
├── default-storage-class-prereqs.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md

バンドル内のファイルに関して、いくつか重要な注意点があります。

• 翻訳されたバンドルに対しては、コンテンツ以外の見つからなかったファイルは上位の言語から継承されます。これにより重複が回避できます。
• バンドル内のすべてのファイルは、HugoがResourcesと呼ぶファイルになり、フロントマター(YAMLファイルなど)をサポートしていない場合であっても、言語ごとにパラメーターやタイトルなどのメタデータを提供できます。詳しくは、Page Resourcesメタデータを参照してください。
• Resourceの.RelPermalinkから取得した値は、ページからの相対的なものとなっています。詳しくは、Permalinksを参照してください。

スタイル

このサイトのスタイルシートのSASSのソースは、assets/sassに置かれていて、Hugoによって自動的にビルドされます。

次の項目

• カスタムのHugo shortcodeについて学ぶ
• スタイルガイドについて学ぶ
• コンテンツガイドについて学ぶ

3 - カスタムHugoショートコード

このページではKubernetesのマークダウンドキュメント内で使用できるHugoショートコードについて説明します。

ショートコードについての詳細はHugoのドキュメントを読んでください。

機能の状態

このサイトのマークダウンページ(.mdファイル)内では、説明されている機能のバージョンや状態を表示するためにショートコードを使用することができます。

機能の状態のデモ

最新のKubernetesバージョンで機能をstableとして表示するためのデモスニペットを次に示します。

{{< feature-state state="stable" >}}

これは次の様に表示されます:

stateの値として妥当な値は次のいずれかです:

• alpha
• beta
• deprecated
• stable

機能の状態コード

表示されるKubernetesのバージョンのデフォルトはそのページのデフォルトまたはサイトのデフォルトです。 for_k8s_versionパラメーターを渡すことにより、機能の状態バージョンを変更することができます。 例えば:

{{< feature-state for_k8s_version="v1.10" state="beta" >}}

これは次の様に表示されます:

用語集

用語集に関連するショートコードとして、glossary_tooltipとglossary_definitionの二つがあります。

コンテンツを自動的に更新し、用語集へのリンクを付与する挿入を使用して、用語を参照することができます。 用語がマウスオーバーされると、用語集の内容がツールチップとして表示されます。 また、用語はリンクとして表示されます。

ツールチップの挿入と同様に、用語集の定義も再利用することができます。

用語集の用語データはglossaryディレクトリに、それぞれの用語のファイルとして保存されています。

用語集のデモ

例えば、マークダウン内でツールチップ付きのclusterを表示するには、次の挿入を使用します:

{{< glossary_tooltip text="cluster" term_id="cluster" >}}

用語集の定義はこのようにします:

{{< glossary_definition prepend="A cluster is" term_id="cluster" length="short" >}}

これは次の様に表示されます:

A cluster is コンテナ化されたアプリケーションを実行する、ノードと呼ばれるワーカーマシンの集合です。すべてのクラスターには少なくとも1つのワーカーノードがあります。

完全な用語定義を挿入することもできます:

{{< glossary_definition term_id="cluster" length="all" >}}

これは次の様に表示されます:

コンテナ化されたアプリケーションを実行する、ノードと呼ばれるワーカーマシンの集合です。すべてのクラスターには少なくとも1つのワーカーノードがあります。

ワーカーノードは、アプリケーションのコンポーネントであるPodをホストします。マスターノードは、クラスター内のワーカーノードとPodを管理します。複数のマスターノードを使用して、クラスターにフェイルオーバーと高可用性を提供します。 ワーカーノードは、アプリケーションワークロードのコンポーネントであるPodをホストします。コントロールプレーンは、クラスター内のワーカーノードとPodを管理します。本番環境では、コントロールプレーンは複数のコンピューターを使用し、クラスターは複数のノードを使用し、耐障害性や高可用性を提供します。

APIリファレンスへのリンク

api-referenceショートコードを使用することで、Kubernetes APIリファレンスへのリンクを作成することができます。 例えば、 Podへの参照方法は次の通りです:

{{< api-reference page="workload-resources/pod-v1" >}}

pageパラメーターの値はAPIリファレンスページのURLの末尾です。

anchorパラメーターを指定することでページ内の特定の場所へリンクすることもできます。 例えば、 PodSpecや environment-variablesへのリンクは次の様に書きます:

{{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}}
{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}}

textパラメーターを指定することでリンクテキストを変更することもできます。 例えば、 Environment Variablesへのリンクは次の様に書きます:

{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variable" >}}

テーブルキャプション

テーブルキャプションを追加することで、表をスクリーンリーダーにとってよりアクセスしやすいものにする事ができます。 表へキャプションを追加するには、表をtableショートコードで囲い、captionパラメーターにキャプションを指定します。

例えば、次の様に書きます:

{{< table caption="Configuration parameters" >}}
Parameter | Description | Default
:---------|:------------|:-------
`timeout` | The timeout for requests | `30s`
`logLevel` | The log level for log output | `INFO`
{{< /table >}}

これは次の様に表示されます:

この表に対するHTMLを検査すると、次の要素が<table>要素のすぐ次にあるのを見ることができるでしょう:

<caption style="display: none;">Configuration parameters</caption>

タブ

このサイトのマークダウンページ(.mdファイル)内では、あるソリューションに対する複数のフレーバーを表示するためのタブセットを追加することができます。

tabsショートコードはこれらのパラメーターを受けとります:

• name: タブに表示される名前
• codelang: 内側のtabショートコードにこれを指定した場合、Hugoはハイライトに使用するコード言語を知ることができます。
• include: タブ内で挿入するファイル。Hugo leaf bundle内にタブがある場合そのファイル(HugoがサポートしているどのMIMEタイプでも良い)はそのbundle自身によって探されます。 もしそうでない場合、そのコンテントページは現在のページから相対的に探されます。 includeを使う場合、ショートコードの内部コンテンツはなく、自己終了構文を使用する必要があることに注意してください。 例えば、{{< tab name="Content File #1" include="example1" />}}の様にします。 codelangを指定するか、ファイル名から言語が特定される必要があります。 非コンテンツファイルはデフォルトでコードが強調表示されます。
• もし内部コンテンツがマークダウンの場合、タブの周りに%デリミターを使用する必要があります。 例えば、{{% tab name="Tab 1" %}}This is **markdown**{{% /tab %}}の様にします。
• タブセット内で、上記で説明したバリエーションを組み合わせることができます。

タブショートコードの例を次に示します。

タブのデモ: コードハイライト

{{< tabs name="tab_with_code" >}}
{{{< tab name="Tab 1" codelang="bash" >}}
echo "これはタブ1です。"
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "これはタブ2です。"
{{< /tab >}}}
{{< /tabs >}}

これは次の様に表示されます:

• Tab 1
• Tab 2

echo "これはタブ1です。"

println "これはタブ2です。"

タブのデモ: インラインマークダウンとHTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
これは**なにがしかのマークダウン**です。
{{< note >}}
ショートコードを含むこともできます。
{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
	<h3>プレーンHTML</h3>
	<p>これはなにがしかの<i>プレーン</i>HTMLです。</p>
</div>
{{< /tab >}}
{{< /tabs >}}

これは次の様に表示されます。

• Markdown
• HTML

タブのデモ: ファイルの読み込み

{{< tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}}
{{< /tabs >}}

これは次の様に表示されます:

• Content File #1
• Content File #2
• JSON File

  {
    "apiVersion": "v1",
    "kind": "PodTemplate",
    "metadata": {
      "name": "nginx"
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "nginx"
        },
        "generateName": "nginx-"
      },
      "spec": {
         "containers": [{
           "name": "nginx",
           "image": "dockerfile/nginx",
           "ports": [{"containerPort": 80}]
         }]
      }
    }
  }

サードパーティーコンテンツマーカー

Kubernetesの実行にはサードパーティーのソフトウェアが必要です。 例えば、名前解決を行うためにはクラスターにDNSサーバーを追加する必要があります。

私たちがサードパーティーソフトウェアにリンクするときや言及するときは、コンテンツガイドに従い、サードパーティーのものに印をつけます。

これらのショートコードを使用すると、それらを使用しているドキュメントページに免責事項が追加されます。

リスト

サードパーティーのリストには、

{{% thirdparty-content %}}

をすべてのアイテムを含むセクションのヘッダーのすぐ下に追加します。

アイテム

ほとんどのアイテムがプロジェクト内ソフトウェア(例えばKubernetes自体やDeschedulerコンポーネント)を参照している場合、違う形を使用することができます。

次のショートコードをアイテムの前か、特定のアイテムのヘッダーのすぐ下に追加します:

{{% thirdparty-content single="true" %}}

バージョン文字列

ドキュメント内でバージョン文字列を生成して挿入するために、いくつかのバージョンショートコードから選んで使用することができます。 それぞれのバージョンショートコードはサイトの設定ファイル(hugo.toml)から取得したバージョンパラメーターの値を使用してバージョン文字列を表示します。 最もよく使われる二つのバージョンパラメーターはlatestとversionです。

{{< param "version" >}}

{{< param "version" >}}ショートコードはサイトのversionパラメーターに設定されたKubernetesドキュメントの現在のバージョンを生成します。 paramショートコードはサイトパラメーターの名前の一つを受けとり、この場合はversionを渡しています。

これは次の様に表示されます:

{{< latest-version >}}

{{< latest-version >}}ショートコードはサイトのlatestパラメーターの値を返します。 サイトのlatestパラメーターは新しいドキュメントのバージョンがリリースされた時に更新されます。 このパラメーターは必ずしもversionの値と一致しません。

これは次の様に表示されます:

{{< latest-semver >}}

{{< latest-semver >}}ショートコードはlatestから"v"接頭辞を取り除いた値を生成します。

これは次の様に表示されます。

{{< version-check >}}

{{< version-check >}}ショートコードはページにmin-kubernetes-server-versionパラメーターがあるかどうか確認し、versionと比較するために使用します。

これは次の様に表示されます:

{{< latest-release-notes >}}

{{< latest-release-notes >}}ショートコードはlatestからバージョン文字列を生成し、"v"接頭辞を取り除きます。 このショートコードはバージョン文字列に対応したリリースノートCHANGELOGページのURLを表示します。

これは次の様に表示されます:

次の項目

• Hugoについて学ぶ。
• 新しいトピックの書き方について学ぶ。
• ページコンテンツタイプについて学ぶ。
• Pull Requestの作り方について学ぶ。
• 発展的コントリビュートについて学ぶ。