このセクション内のトピックでは、文章のスタイル、コンテンツの形式や構成、特にKubernetesのドキュメント特有のHugoカスタマイズの使用方法に関するガイダンスを提供します。
これは、このセクションの複数ページの印刷可能なビューです。 印刷するには、ここをクリックしてください.
ドキュメントスタイルの概要
- 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のプロジェクトのメンテナーであり、ドキュメントのホスティングに関して手助けが必要なときは、Kubernetes Slackの#sig-docsで教えてください。その他の情報
許可されるコンテンツに関して疑問がある場合は、Kubernetes Slackの#sig-docsチャンネルに参加して質問してください!
次の項目
- スタイルガイドを読む
2 - コンテンツの構造化
このサイトではHugoを使用しています。Hugoでは、コンテンツの構造化がコアコンセプトとなっています。
備考:
Hugoのヒント: コンテンツの編集を始めるときは、hugo server --navigateToChanged
コマンドを使用してHugoを実行してください。ページの一覧
ページの順序
ドキュメントのサイドメニューやページブラウザーなどでは、Hugoのデフォルトのソート順序を使用して一覧を作成しています。デフォルトでは、weight(1から開始)、日付(最新のものが1番目)、最後にリンクのタイトルの順でソートされます。
そのため、特定のページやセッションを上に移動したい場合には、ページのフロントマター内のweightを設定します。
title: My Page
weight: 10
備考:
ページのweightについては、1、2、3…などの値を使用せず、10、20、30…のように一定の間隔を空けた方が賢明です。こうすることで、後で別のページを間に挿入できるようになります。さらに、同じディレクトリ(セクション)内の各ページのweightは、重複しないようにする必要があります。これにより、特にローカライズされたコンテンツでは、コンテンツが常に正しく整列されるようになります。ドキュメントのメインメニュー
ドキュメントのメインメニューは、docs/
以下に置かれたセクションのコンテンツファイル_index.md
のフロントマター内にmain_menu
フラグが設定されたものから生成されます。
main_menu: true
リンクのタイトルは、ページのlinkTitle
から取得されることに注意してください。そのため、ページのタイトルとは異なるリンクテキストにしたい場合、コンテンツファイル内の値を以下のように設定します。
main_menu: true
title: ページタイトル
linkTitle: リンク内で使われるタイトル
備考:
上記の設定は言語ごとに行う必要があります。メニュー上にセクションが表示されないときは、Hugoからセクションとして認識されていないためである可能性が高いです。セクションフォルダー内に_index.md
コンテンツファイルを作成してください。ドキュメントのサイドメニュー
ドキュメントのサイドバーメニューは、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" >}}
これは次の様に表示されます:
Kubernetes v1.31 [stable]
state
の値として妥当な値は次のいずれかです:
- alpha
- beta
- deprecated
- stable
機能の状態コード
表示されるKubernetesのバージョンのデフォルトはそのページのデフォルトまたはサイトのデフォルトです。
for_k8s_version
パラメーターを渡すことにより、機能の状態バージョンを変更することができます。
例えば:
{{< feature-state for_k8s_version="v1.10" state="beta" >}}
これは次の様に表示されます:
Kubernetes v1.10 [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
パラメーターにキャプションを指定します。
備考:
テーブルキャプションはスクリーンリーダーからは読むことができますが、標準的なHTMLでは読むことができません。例えば、次の様に書きます:
{{< table caption="Configuration parameters" >}}
Parameter | Description | Default
:---------|:------------|:-------
`timeout` | The timeout for requests | `30s`
`logLevel` | The log level for log output | `INFO`
{{< /table >}}
これは次の様に表示されます:
Parameter | Description | Default |
---|---|---|
timeout |
The timeout for requests | 30s |
logLevel |
The log level for log output | INFO |
この表に対する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はコンテンツページ内でユニークである必要があります。タブのデモ: コードハイライト
{{< tabs name="tab_with_code" >}}
{{{< tab name="Tab 1" codelang="bash" >}}
echo "これはタブ1です。"
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "これはタブ2です。"
{{< /tab >}}}
{{< /tabs >}}
これは次の様に表示されます:
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 >}}
これは次の様に表示されます。
これはなにがしかのマークダウンです。
備考:
ショートコードを含むこともできます。
プレーンHTML
これはなにがしかのプレーン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 >}}
これは次の様に表示されます:
これは挿入leaf bundle内のコンテンツファイルの例です。
備考:
挿入されたコンテンツファイル内でもショートコードを使用することができます。これは挿入leaf bundle内のコンテンツファイルのもう一つの例です
{
"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
は変更されません。
例えば、以前にリリースされたドキュメントはversion
をv1.19
として表示し、latest
をv1.20
として表示します。これは次の様に表示されます:
v1.31{{< latest-version >}}
{{< latest-version >}}
ショートコードはサイトのlatest
パラメーターの値を返します。
サイトのlatest
パラメーターは新しいドキュメントのバージョンがリリースされた時に更新されます。
このパラメーターは必ずしもversion
の値と一致しません。
これは次の様に表示されます:
v1.31{{< latest-semver >}}
{{< latest-semver >}}
ショートコードはlatest
から"v"接頭辞を取り除いた値を生成します。
これは次の様に表示されます。
1.31{{< version-check >}}
{{< version-check >}}
ショートコードはページにmin-kubernetes-server-version
パラメーターがあるかどうか確認し、version
と比較するために使用します。
これは次の様に表示されます:
バージョンを確認するには次のコマンドを実行してください:kubectl version
.
{{< latest-release-notes >}}
{{< latest-release-notes >}}
ショートコードはlatest
からバージョン文字列を生成し、"v"接頭辞を取り除きます。
このショートコードはバージョン文字列に対応したリリースノートCHANGELOGページのURLを表示します。
これは次の様に表示されます:
https://git.k8s.io/kubernetes/CHANGELOG/CHANGELOG-1.31.md次の項目
- Hugoについて学ぶ。
- 新しいトピックの書き方について学ぶ。
- ページコンテンツタイプについて学ぶ。
- Pull Requestの作り方について学ぶ。
- 発展的コントリビュートについて学ぶ。