docs-gen v0.6.0

アーキテクチャ

アーキテクチャ

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       共通ヘルパー（再帰的ディレクトリコピー）

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 に組み込めるようになっています。

ESC