このセクション内のトピックでは、文章のスタイル、コンテンツの形式や構成、特にKubernetesのドキュメント特有の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…のように一定の間隔を空けた方が賢明です。こうすることで、後で別のページを間に挿入できるようになります。
ドキュメントのメインメニュー
ドキュメントのメインメニューは、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について学ぶ
- スタイルガイドについて学ぶ
- コンテンツガイドについて学ぶ