Merge upstream work for release-1.19
This commit is contained in:
inductor
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: ドキュメントコンテンツガイド
|
||||
linktitle: コンテンツガイド
|
||||
content_type: concept
|
||||
weight: 10
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
このページでは、Kubernetesのドキュメント上のコンテンツのガイドラインを説明します。
|
||||
|
||||
許可されるコンテンツに関して疑問がある場合は、[Kubernetes Slack](https://slack.k8s.io/)の#sig-docsチャンネルに参加して質問してください！
|
||||
|
||||
Kubernetes Slackには、<https://slack.k8s.io/> から参加登録ができます。
|
||||
|
||||
Kubernetesドキュメントの新しいコンテンツの作成に関する情報については、[スタイルガイド](/docs/contribute/style/style-guide)に従ってください。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
## 概要
|
||||
|
||||
ドキュメントを含むKubernetesのウェブサイトのソースは、[kubernetes/website](https://github.com/kubernetes/website)リポジトリに置かれています。
|
||||
|
||||
Kubernetesの主要なドキュメントは`kubernetes/website/content/<language_code>/docs`フォルダに置かれており、これらは[Kubernetesプロジェクト](https://github.com/kubernetes/kubernetes)を対象としています。
|
||||
|
||||
## 許可されるコンテンツ
|
||||
|
||||
Kubernetesのドキュメントにサードパーティーのコンテンツを掲載することが許されるのは、次の場合のみです。
|
||||
|
||||
- コンテンツがKubernetesプロジェクト内のソフトウェアのドキュメントとなる場合
|
||||
- コンテンツがプロジェクト外のソフトウェアのドキュメントとなるが、Kubernetesを機能させるために必要である場合
|
||||
- コンテンツがkubernetes.ioの正規のコンテンツであるか、他の場所の正規のコンテンツへのリンクである場合
|
||||
|
||||
### サードパーティーのコンテンツ
|
||||
|
||||
Kubernetesのドキュメントには、Kubernetesプロジェクト([kubernetes](https://github.com/kubernetes)および[kubernetes-sigs](https://github.com/kubernetes-sigs) GitHub organizationsに存在するプロジェクト)の適用例が含まれています。
|
||||
|
||||
Kubernetesプロジェクト内のアクティブなコンテンツへのリンクは常に許可されます。
|
||||
|
||||
Kubernetesを機能させるためには、一部サードパーティーのコンテンツが必要です。たとえば、コンテナランタイム(containerd、CRI-O、Docker)、[ネットワークポリシー](/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/)(CNI plugin)、[Ingressコントローラー](/ja/docs/concepts/services-networking/ingress-controllers/)、[ロギング](/docs/concepts/cluster-administration/logging/)などです。
|
||||
|
||||
ドキュメント内で、Kubernetesプロジェクト外のサードパーティーのオープンソースソフトウェア(OSS)にリンクすることができるのは、Kubernetesを機能させるために必要な場合のみです。
|
||||
|
||||
### 情報源が重複するコンテンツ
|
||||
|
||||
可能な限り、Kubernetesのドキュメントは正規の情報源にリンクするようにし、情報源が重複してしまうようなホスティングは行いません。
|
||||
|
||||
情報源が重複したコンテンツは、メンテナンスするために2倍の労力(あるいはそれ以上！)が必要になり、より早く情報が古くなってしまいます。
|
||||
|
||||
{{< note >}}
|
||||
|
||||
あなたがKubernetesのプロジェクトのメンテナーであり、ドキュメントのホスティングに関して手助けが必要なときは、[Kubernetes Slackの#sig-docs](https://kubernetes.slack.com/messages/C1J0BPD2M/)で教えてください。
|
||||
|
||||
{{< /note >}}
|
||||
|
||||
### その他の情報
|
||||
|
||||
許可されるコンテンツに関して疑問がある場合は、[Kubernetes Slack](https://slack.k8s.io/)の#sig-docsチャンネルに参加して質問してください！
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* [スタイルガイド](/docs/contribute/style/style-guide)を読む
|
||||
@@ -0,0 +1,123 @@
|
||||
---
|
||||
title: コンテンツの構造化
|
||||
content_type: concept
|
||||
weight: 40
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
このサイトではHugoを使用しています。Hugoでは、[コンテンツの構造化](https://gohugo.io/content-management/organization/)がコアコンセプトとなっています。
|
||||
|
||||
<!-- body -->
|
||||
|
||||
{{% note %}}
|
||||
**Hugoのヒント:** コンテンツの編集を始めるときは、`hugo server --navigateToChanged`コマンドを使用してHugoを実行してください。
|
||||
{{% /note %}}
|
||||
|
||||
## ページの一覧
|
||||
|
||||
### ページの順序
|
||||
|
||||
ドキュメントのサイドメニューやページブラウザーなどでは、Hugoのデフォルトのソート順序を使用して一覧を作成しています。デフォルトでは、weight(1から開始)、日付(最新のものが1番目)、最後にリンクのタイトルの順でソートされます。
|
||||
|
||||
そのため、特定のページやセッションを上に移動したい場合には、ページのフロントマター内のweightを設定します。
|
||||
|
||||
```yaml
|
||||
title: My Page
|
||||
weight: 10
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
ページのweightについては、1、2、3…などの値を使用せず、10、20、30…のように一定の間隔を空けた方が賢明です。こうすることで、後で別のページを間に挿入できるようになります。
|
||||
{{% /note %}}
|
||||
|
||||
### ドキュメントのメインメニュー
|
||||
|
||||
ドキュメントのメインメニューは、`docs/`以下に置かれたセクションのコンテンツファイル`_index.md`のフロントマター内に`main_menu`フラグが設定されたものから生成されます。
|
||||
|
||||
```yaml
|
||||
main_menu: true
|
||||
```
|
||||
|
||||
リンクのタイトルは、ページの`linkTitle`から取得されることに注意してください。そのため、ページのタイトルとは異なるリンクテキストにしたい場合、コンテンツファイル内の値を以下のように設定します。
|
||||
|
||||
```yaml
|
||||
main_menu: true
|
||||
title: ページタイトル
|
||||
linkTitle: リンク内で使われるタイトル
|
||||
```
|
||||
|
||||
{{% note %}}
|
||||
上記の設定は言語ごとに行う必要があります。メニュー上にセクションが表示されないときは、Hugoからセクションとして認識されていないためである可能性が高いです。セクションフォルダー内に`_index.md`コンテンツファイルを作成してください。
|
||||
{{% /note %}}
|
||||
|
||||
### ドキュメントのサイドメニュー
|
||||
|
||||
ドキュメントのサイドバーメニューは、`docs/`以下の*現在のセクションツリー*から生成されます。
|
||||
|
||||
セクションと、そのセクション内のページがすべて表示されます。
|
||||
|
||||
特定のセクションやページをリストに表示したくない場合、フロントマター内の`toc_hide`フラグを`true`に設定してください。
|
||||
|
||||
```yaml
|
||||
toc_hide: true
|
||||
```
|
||||
|
||||
コンテンツが存在するセクションに移動すると、特定のセクションまたはページ(例:`index.md`)が表示されます。それ以外の場合、そのセクションの最初のページが表示されます。
|
||||
|
||||
### ドキュメントのブラウザー
|
||||
|
||||
ドキュメントのホームページのページブラウザーは、`docs`セクション直下のすべてのセクションとページを使用して生成されています。
|
||||
|
||||
特定のセクションやページを表示したくない場合、フロントマターの`toc_hide`フラグを`true`に設定してください。
|
||||
|
||||
```yaml
|
||||
toc_hide: true
|
||||
```
|
||||
|
||||
### メインメニュー
|
||||
|
||||
右上のメニュー(およびフッター)にあるサイトリンクは、page-lookupの機能を使用して実装されています。これにより、ページが実際に存在することを保証しています。そのため、たとえば`case-studies`のセクションが特定の言語のサイトに存在しない場合、メニューにはケーススタディのリンクが表示されません。
|
||||
|
||||
## Page Bundle
|
||||
|
||||
スタンドアローンのコンテンツページ(Markdownファイル)に加えて、Hugoでは、[Page Bundles](https://gohugo.io/content-management/page-bundles/)がサポートされています。
|
||||
|
||||
Page Bundleの1つの例は、[カスタムのHugo Shortcode](/docs/contribute/style/hugo-shortcodes/)です。これは、`leaf bundle`であると見做されます。ディレクトリ内のすべてのファイルは、`index.md`を含めてバンドルの一部となります。これには、ページからの相対リンク、処理可能な画像なども含まれます。
|
||||
|
||||
```bash
|
||||
en/docs/home/contribute/includes
|
||||
├── example1.md
|
||||
├── example2.md
|
||||
├── index.md
|
||||
└── podtemplate.json
|
||||
```
|
||||
|
||||
もう1つのPage Bundleがよく使われる例は、`includes`バンドルです。フロントマターに`headless: true`を設定すると、自分自身のURLを持たなくなり、他のページ内でのみ使用されるようになります。
|
||||
|
||||
```bash
|
||||
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メタデータ](https://gohugo.io/content-management/page-resources/#page-resources-metadata)を参照してください。
|
||||
* `Resource`の`.RelPermalink`から取得した値は、ページからの相対的なものとなっています。詳しくは、[Permalinks](https://gohugo.io/content-management/urls/#permalinks)を参照してください。
|
||||
|
||||
## スタイル
|
||||
|
||||
このサイトのスタイルシートの[SASS](https://sass-lang.com/)のソースは、`assets/sass`に置かれていて、Hugoによって自動的にビルドされます。
|
||||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* [カスタムのHugo shortcode](/docs/contribute/style/hugo-shortcodes/)について学ぶ
|
||||
* [スタイルガイド](/docs/contribute/style/style-guide)について学ぶ
|
||||
* [コンテンツガイド](/docs/contribute/style/content-guide)について学ぶ
|
||||
Reference in New Issue
Block a user