02. サイト構築規定

このドキュメントは、本プロジェクトのドキュメントソース（Markdown）から、静的ドキュメントサイトを構築し、公開するための技術的なルールと手順を定めます。

1. 基本方針

目的: ドキュメントの可読性と保守性を高めるため、一貫したルールに基づいてドキュメントサイトを構築します。
単一の情報源: サイトの構造や設定は、この規定と関連する設定ファイル（mkdocs.yml）で一元管理します。

2. サイト構築ツール

ジェネレータ: 本プロジェクトでは、静的サイトジェネレータとして MkDocs を利用します。
テーマ: 可読性と機能性に優れた Material for MkDocs テーマを利用します。
プラグイン:
- mkdocs-awesome-pages-plugin: ナビゲーションの自動生成に利用します。
- mkdocs-exclude: ビルド対象から特定のファイルを除外するために利用します。

3. ナビゲーション管理

サイトのナビゲーションは、トップレベルのタブとサイドバーの2段階で構成されます。このナビゲーションはmkdocs-awesome-pages-pluginによって、原則として自動で構築されます。

3.1. 基本構成と自動化ルール

基本構成:
- トップレベルタブ: Docs/直下のカテゴリフォルダ（例: 01_要求仕様/）が、サイト上部のタブ項目として自動で表示されます。
- サイドバー: ユーザーがタブを選択すると、そのカテゴリ内のドキュメントが、ファイル名の数字プレフィックス順にサイドバーへツリー表示されます。
タブ機能の有効化: この構成を実現するため、mkdocs.ymlのtheme:セクションでタブ機能を有効化します。
```
theme:
    name: material
    features:
        - navigation.tabs
```

3.2. 手動での例外設定（ハイブリッドアプローチ）

自動生成のルールに例外を加えたい場合は、mkdocs.ymlのnavセクションや、各ファイル・フォルダでの個別設定を併用します。

3.2.1. ホームページの追加 (`mkdocs.yml`)

Docs/のフォルダ構造に基づかない「ホーム」のような特別なタブを追加する場合は、mkdocs.ymlのnav:セクションに明示的に記述します。

# mkdocs.yml

nav:
    - ホーム: README.md
# 他の項目はawesome-pagesが自動で追加するため、記述しない

3.2.2. 特定フォルダのナビゲーション制御 (`.pages`ファイル)

特定のフォルダ内での表示順序やタイトルを厳密に制御したい場合は、そのフォルダ直下に.pagesというファイルを作成し、ナビゲーションを定義します。.pagesファイルがないフォルダは、引き続き自動モードで動作します。

3.2.3. 特定ファイルのナビゲーション制御 (フロントマター)

個別のファイルをナビゲーションから非表示にしたり、タイトルを上書きしたりする場合は、対象ファイルのフロントマター（---で囲まれた先頭部分）に記述します。

非表示にする場合:
```
---
hide: true
---
```
タイトルを上書きする場合:
```
---
title: 特別なタイトル
---
```

4. ビルド対象からのファイル除外

mkdocs-excludeプラグインを利用して、サイトに含めたくないファイルやフォルダをビルド対象から除外します。

README.mdの扱い: GitHub閲覧用のREADME.mdは、Docs/直下のものを除き、すべてビルド対象から除外します。
【重要】プラグインの順序: excludeプラグインは、ナビゲーションが生成される前に不要なファイルを取り除くため、必ずawesome-pagesプラグインよりも前に記述する必要があります。

設定例 (mkdocs.yml):

plugins:
    - search
    # 最初に不要なファイルを除外
    - exclude:
          glob:
              - '**/README.md'
              - '!README.md' # Docs/直下のREADMEは除外しない
              - '**/bin/**'
              - '**/obj/**'
    # 除外後のファイルリストでナビゲーションを自動生成
    - awesome-pages

5. ローカル環境でのプレビュー

ドキュメントの変更をコミットする前に、ローカル環境で表示崩れやリンク切れがないかを確認することを強く推奨します。

必要なツールのインストール:

pip install mkdocs-material mkdocs-awesome-pages-plugin mkdocs-exclude pymdown-extensions mkdocs-git-revision-date-localized-plugin

プレビューサーバーの起動: リポジトリのルートディレクトリで以下のコマンドを実行します。
```
mkdocs serve
```
ブラウザで確認: http://127.0.0.1:8000 にアクセスし、変更内容を確認します。

6. サイトの公開（デプロイ）

ホスティング: 本プロジェクトのドキュメントサイトは、GitHub Pagesを利用して公開します。
自動デプロイ: mainブランチへのマージをトリガーとして、GitHub Actionsのワークフローが自動的にサイトをビルドし、デプロイします。
Actionsの設定: ワークフローファイル内のライブラリインストールコマンドには、本規定で利用する全てのプラグインを含める必要があります。
```
# GitHub Actions ワークフローファイル内
- name: Install dependencies
  run: pip install mkdocs-material mkdocs-awesome-pages-plugin mkdocs-exclude
```