カスタムドキュメントバンドル構造

カスタムドキュメントバンドルの ordering.md ファイルは、バンドル内のページの構造と編成を決定します。ドキュメントバンドル内の各ページには セクション注釈 を指定する必要があります。利用可能なセクション注釈のセットは事前に決められており、変更することはできません。

ファイル構造

ユーザーのドキュメントリポジトリ内で、プロジェクトの構造は次のようになります。

docs/
├── product-A/
│   └── concepts
│       └── concept-doc.md  # 概念に関するドキュメント
│   └── tutorials
│       └── tutorial-doc.md  # チュートリアルのドキュメント
│   └── ordering.md  # 注文方法に関するドキュメント
│   └── overview.md  # 概要に関するドキュメント
└── product-B/
    └── ...  # 他のプロダクトのドキュメント

すべてのドキュメントは、バンドルとして docs/ フォルダーの下にネストする必要があります（上記の product-A のように）。
これらのバンドルフォルダーは、プラットフォーム内のカスタムドキュメントのホームページに表示される製品セットに対応しています。
すべてのバンドルには、製品フォルダーレベルで ordering.md と overview.md ファイルが含まれている必要があります。
各「製品」の下にネストされる実際のフォルダーおよびファイル（上記の例の concepts および tutorials フォルダーなど）は、ユーザーのニーズに合わせてカスタマイズできます。

目次と `ordering.md`

バンドル内のすべてのドキュメントページは、セクション注釈とファイル名（.md 拡張子を含まない）を使用して ordering.md ファイルにリストされる必要があります。カスタムドキュメントサービスがドキュメントを検出してコンパイルするときに、これらのセクション注釈が使用されて左側の目次が構築されます。

セクション注釈

プラットフォーム内のカスタムドキュメントには、コンテンツページを整理する方法を決定するために ordering.md ファイルで使用できる一連のセクション注釈があります。

現在存在するセクション注釈は次のとおりです。

@quickstart
@howto
@tutorial
@concept
@resource
@api
@reference

ドキュメントバンドル内のすべてのページにセクション注釈が必要ですが、すべてのセクション注釈を使用する必要はありません。

セクション注釈の概要

プラットフォーム内のカスタムドキュメントサービスは、セクション注釈によって標準構造を強制します。以下は利用可能なセクションの一般的なガイドラインですが、適宜セクションを使用することを推奨します。

Overview: overview.md から生成され、カスタムドキュメントバンドルのホームページです。
Quick Starts: 製品の基本を簡単に説明するガイド。初めてのユーザーはここから始め、製品の使用を開始できるだけの知識を得ることができます。
Concepts: アプリケーション/サービスに関連するコアアイデアと概念。これは必ずしも実行可能な内容ではありませんが、何かがどのように、またはなぜそのように機能するのかを説明するために役立つ重要な概念を説明します。
How To: 一般的で自己完結型のタスクをユーザーが達成するのを助けるガイド。
Tutorials: 一連のタスクを完了することで特定の結果を達成するためのステップバイステップガイド。チュートリアルはエンドツーエンドのワークフローを概説するために使用されることがあり、ユーザーが従うのを助けるために仮のデータを使用することがよくあります。
References: 構文、型、およびその他の情報に関する技術リファレンス。
Resources: 内部および外部のリソース、たとえば有用なリンクやFAQ。
APIs: 製品のAPIエンドポイント。

`ordering.md` の例

ドキュメントバンドル内のすべてのページは、セクション注釈とファイル名（.md ファイル拡張子を含まない）を使用して ordering.md にリストされる必要があります。たとえば、Contour の ordering ファイルは次のようになります:

@quickstart getting-started  # クイックスタートガイド: はじめに
@concept core-concepts       # コンセプト: コアコンセプト
@resource faq                # リソース: よくある質問（FAQ）
@howto boards-add            # ハウツー: ボードの追加
@howto boards-filter         # ハウツー: ボードのフィルタリング
@howto boards-join           # ハウツー: ボードへの参加
@howto boards-verify-results # ハウツー: 結果の検証
@reference boards-descriptions # リファレンス: ボードの説明
@tutorial boards-map         # チュートリアル: ボードのマッピング

ordering.md に表示されるファイル名の順序は、目次の順序を決定します。上記の例の ordering.md ファイルの目次には、「How Tos」ヘッダーが含まれ、最初に「Add boards」 (@howto boards-add)、次に「Filter boards」 (@howto boards-filter) などがリストされます。

子ページを使用したドキュメントのネスト

目次の最上位にドキュメントページを表示させたくない場合は、代わりに別のページの下にネストさせることができます。カスタムドキュメントでは、子<>親の関係を宣言する方法が 2 つあります。

[推奨] 親ページで子ページを宣言する
[非推奨] 子ページで親ページを宣言する

親ページで子ページを宣言する

親ページで @child 注釈を使用してページを子としてネストできます。これにより、これらの子ページが親ページの下にネストされる順序を指定できます。たとえば、example-parent-page.md を以下のようにすることができます。

@title Parent

@child page-one  # 子ページ1
@child page-two  # 子ページ2
@child page-three  # 子ページ3

@child アノテーションの順序は、目次にページがリストされる順序を決定します。子ページは ordering.md ファイルに含める必要はありません。親ページがリストされている限り、ドキュメンテーションサービスは子ページを公開します。

子ページに親を宣言する

同じバンドル内のファイルを参照する場合は、@child を使用し、@parent を使用すべきではありません。@child を使用すると子ページの順序を指定できるため、@child は @parent よりも表現力が高いです。@parent は、親ページが子ページの存在を知らない場合にのみ使用すべきです（たとえば、別のバンドルの Contour ボードページにカスタム Contour ボードを子として追加する場合）。

ページを作成していて、そのページに親ページがあることがわかっている場合は、ファイルの先頭に @parent アノテーションを次のように使用できます: @parent parent-filename。@child または @parent のいずれか一方を使用するだけでよく、両方を使用する必要はありません。