---
title: アーキテクチャ
order: 2
---

## アーキテクチャ

docs-gen はシングルバイナリの静的サイトジェネレーターです。ソースコードはすべて `src/` に、組み込みアセットはすべて `defaults/` にあります。

### モジュール構成

```
src/
├── main.rs        CLI エントリポイントとコマンド（init, theme）
├── config.rs      config.toml のパースとバリデーション
├── builder.rs     サイト生成: ページ収集、Tera レンダリング、出力
├── markdown.rs    フロントマターのパースとシンタックスハイライト付き Markdown レンダリング
├── serve.rs       ライブリロード付き開発サーバー（HTTP + WebSocket）
├── check.rs       ソース検証（壊れたリンク、order の問題、参照されていないページ）
├── defaults.rs    テーマとスキャフォールドファイルのコンパイル時埋め込み
└── utils.rs       共通ヘルパー（再帰的ディレクトリコピー）
```

### ビルドの仕組み

`docs-gen build src out` を実行すると、次のパイプラインが動きます:

1. **設定の読み込み** — `config.rs` が `config.toml` を読み、テーマ設定（プロジェクトのオーバーライドまたはビルトインデフォルト）をマージします。
2. **Tera のセットアップ** — `builder.rs` がビルトインテンプレートを登録し、その上にプロジェクトレベルのテンプレート（`bases/<name>/templates/` と `templates/`）をオーバーレイします。
3. **ページの収集** — 言語ごとに `pages/<lang>/` を走査し、フロントマターをパースして Markdown を HTML にレンダリングします。
4. **ナビゲーションの構築** — ページをセクションごとにグループ化し、`order` → ファイル名の順でソートして、サイドバーツリーを構築します。
5. **テンプレートのレンダリング** — 各ページに Tera コンテキスト（`site`, `page`, `nav`, `content` など）を渡し、`portal.html` または `page.html` でレンダリングします。
6. **静的ファイルのコピー** — ビルトインテーマの静的ファイルを先に出力し、その上にプロジェクトレベルのオーバーライドをコピーします。
7. **検索インデックスの生成** — `pages-data.json` に各ページのタイトル、URL、プレーンテキスト本文（切り詰め済み）を出力します。
8. **ルートリダイレクト** — 多言語サイトの場合、デフォルト言語に基づいた `index.html` リダイレクトを生成します。

### 組み込みデフォルト

`defaults.rs` は `include_dir!` を使って `defaults/` ディレクトリ全体をコンパイル時に埋め込みます:

- **Base** (`defaults/bases/`) — テンプレート、JS、アイコンなど共通レイアウト基盤。
- **Style** (`defaults/styles/`) — 各ビルトインテーマの CSS と設定ファイル。新しいディレクトリを追加するだけで、コード変更なしに新しいテーマが登録されます。
- **スキャフォールドファイル** (`defaults/config.toml`, `defaults/pages/`) — `docs-gen init` で新しいプロジェクトをブートストラップするときにコピーされます。

### 開発サーバー

`serve.rs` は3つのコンポーネントを並行実行します:

- **HTTP サーバー** (`tiny_http`) — 一時ディレクトリからビルド済みサイトを配信します。クリーンURLルーティング（ディレクトリ → `index.html`）とトレイリングスラッシュリダイレクトを処理します。
- **WebSocket サーバー** (`tungstenite`) — ライブリロード通知用にブラウザからの接続を受け付けます。
- **ファイルウォッチャー** (`notify`) — ソースディレクトリを再帰的に監視します。変更を検出するとサイトを再ビルドし、HTML ファイルにライブリロードスクリプトを挿入して、接続中のすべてのブラウザに `"reload"` メッセージを送信します。冗長なリビルドを避けるため、変更は200msのデバウンス処理されます。

### チェックパイプライン

`check.rs` は HTML をレンダリングせずに、ソースに対して4つの検証パスを実行します:

1. **order の重複** — 同じセクション内で同じ `order` 値を持つページを検出します。
2. **order の未設定** — インデックス以外のページが `order: 0` にデフォルトのままになっている場合に警告します。
3. **壊れた内部リンク** — すべての Markdown リンクをページのレンダリング済みURLパスからの相対で解決し、ターゲットの `.md` ファイルが存在するか確認します。
4. **参照されていないページ** — 他のどのページのコンテンツからもリンクされていないページを検出します。

終了コードは、問題なし（0）、エラーあり（1）、ランタイムエラー（2）を区別し、CI に組み込めるようになっています。
