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

カスタムドキュメントバンドルの 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.md から生成される、カスタムドキュメントバンドルのホームページです。
• クイックスタート： 製品の基本事項を説明する簡潔なガイドです。初めて使用するユーザーはここから始め、製品を使い始めるために十分な知識を得られます。
• 概念： アプリケーションやサービスに関連する中心的な考え方や概念です。必ずしも具体的な操作につながる内容ではありませんが、仕組みやその理由を説明するうえで役立つ重要な概念を説明します。
• 操作方法： 一般的で、ほかのタスクに依存せずに完結する日常的なタスクを支援するガイドです。
• チュートリアル： ユーザーが一連のタスクを完了して特定の結果を達成するために、順を追って進められるガイドです。チュートリアルでは、最初から最後までのワークフローの概要を示すことができ、ユーザーが手順に沿って進めやすいように架空のデータを使用することがよくあります。
• 参照： 構文、データ型、その他の情報に関する技術リファレンスです。
• リソース： 便利なリンクや FAQ など、内部および外部のリソースです。
• API： 製品の API エンドポイントです。

ordering.md の例

ドキュメントバンドル内のすべてのページは、セクション注釈とファイル名（.md ファイル拡張子を除く）を付けて ordering.md に記載する必要があります。たとえば、Contour の順序定義ファイルは次のようになります。

@quickstart getting-started
@concept core-concepts
@resource faq
@howto boards-add
@howto boards-filter
@howto boards-join
@howto boards-verify-results
@reference boards-descriptions
@tutorial boards-map

ordering.md にファイル名を記載する順序によって、目次の順序が決まります。上記の ordering.md ファイルの例では、目次に「操作方法」という見出しが表示され、その下にまず「ボードを追加」（@howto boards-add）、次に「ボードを絞り込む」（@howto boards-filter）という順序でページが並びます。

子ページを使ってドキュメントを入れ子にする

ドキュメントページを目次の最上位に表示せず、別のページの下に入れ子として配置したい場合は、子ページを使用できます。カスタムドキュメントで子と親の関係を宣言するには、2つの方法があります。

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

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

親ページで @child 注釈を使用すると、そのページの子ページとしてほかのページを入れ子にできます。これにより、親ページの下に入れ子で表示される子ページの順序を指定できます。たとえば、example-parent-page.md に次の内容を記載します。

@title Parent

@child page-one
@child page-two
@child page-three

@child 注釈の順序によって、目次にページが表示される順序が決まります。子ページを ordering.md ファイルに含める必要はありません。親ページが記載されていれば、ドキュメントサービスは子ページを公開します。

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

ページを作成する際に、別のページがその親ページになることが分かっている場合は、ファイルの先頭で @parent 注釈を @parent parent-filename のように使用できます。@child または @parent のどちらか一方だけを使用すればよく、両方を使用する必要はありません。