Codexリソース
Codexリソースからドキュメントを自動生成します。
概要
zudo-docは、プロジェクト内のCodexリソースからドキュメントページを自動生成できます。対象となるのは、AGENTS.mdファイル、設定プロファイル、カスタムエージェント、フック、ルール、スキルです。有効にすると、生成されたページはヘッダーナビゲーションのCodexセクションに表示されます。
Codexリソースの有効化
zfb.config.tsでcodexResourcesを設定します：
export default defineConfig(
zudoDoc({
codexResources: {
codexDir: ".codex",
},
}),
);インテグレーションを無効にするにはfalseを設定します：
codexResources: false,生成されるもの
インテグレーションは以下のドキュメントセクションを生成します：
| 生成先ディレクトリ | 内容 | ソース |
|---|---|---|
codex/（位置904） | カテゴリカードを備えた概要ページ | — |
codex-agents-md/（位置905） | すべてのAGENTS.mdとAGENTS.override.md | scanRootから探索 |
codex-config/（位置906） | config.toml、*.config.tomlプロファイル、config.toml.example | .codex/ |
codex-agents/（位置907） | カスタムサブエージェント | .codex/agents/*.toml |
codex-hooks/（位置908） | ライフサイクルフックとフックスクリプト | .と.codex/hooks/ |
codex-rules/（位置909） | コマンド承認ルール | .codex/rules/*.rules |
codex-skills/（位置910） | スキルパッケージ | .codex/skills/と、プロジェクトルートおよびスキャンルートの.agents/skills/ |
リソースごとにインデックスページが作られ、検出された各リソースは個別の詳細ページとして表示されます。
仕組み
インテグレーションは@takazudo/ zfbプラグインとしてビルド時に動作します。codexResourcesが設定されていれば、zudoDoc()がプラグインを自動的に組み込みます。preBuildフックでは次の処理を行います：
projectRoot、scanRoot、設定された.codex/ディレクトリを解決scanRootを探索してAGENTS.mdとAGENTS.override.mdを検出設定された各リソースの場所から、設定、エージェント、フック、ルール、スキルを検出
7つの
codex*ディレクトリにインデックスページと詳細ページのMDXを生成生成したページをzfbのコンテンツコレクションから利用できる状態にする
生成されたページは、ヘッダーナビゲーションのCodexタブに表示されます。すべてのCodex生成セクションでタブをアクティブにするには、categoryMatch: "codex"を設定します。
ヘッダーアイテムにはversioned: falseを設定してください。生成されたCodexコンテンツは/配下には書き込まれないため、バージョン対応のリンクにすると、過去バージョンの表示中に存在しないルートを指してしまいます。
ロケールごとの挙動
概要ページとカテゴリインデックスは、設定済みの各ロケールに生成されます。タイトル、説明、ラベルにはresource.*のUI文字列が使われます。個別リソース本文の正本となるソースダンプはデフォルトのコンテンツディレクトリに置かれます。本文の言語は元のソースファイルに従うため、必ずしも英語ではありません。ロケール付きルートでは未翻訳バナーを出さず、ローカライズされたナビゲーションとクロームの中にその本文を表示します。言語切り替えには設定済みの全ロケールへのリンクが残ります。
パッケージが同梱するresource.*文字列は英語と日本語です。他の対応ロケールコードは、通常どおり要求ロケール → 設定済みデフォルト → 英語 → リテラルの順でフォールバックします。ラベルはZudoDocConfig.translationsで上書きできます。保存方針の理由、llms.txtと検索の挙動、defaultLocaleOnlyPrefixesによるオプトアウトは国際化を参照してください。
設定オプション
| オプション | 型 | 説明 |
|---|---|---|
codexDir | string | .codex/ディレクトリへのパス。projectRootを基準に解決 |
projectRoot | string | 省略可能なプロジェクトルートの上書き。codexDirと生成先のdocsDirはこのルートを基準に解決 |
scanRoot | string | 省略可能なリポジトリ全体の探索ルート。デフォルトはprojectRootで、AGENTS.md / AGENTS.override.mdの探索と、リポジトリレベルの.agents/skills/ルートの両方に適用 |
Note
スキルは<codexDir>/skills/、<projectRoot>/.agents/skills/、<scanRoot>/.agents/skills/の優先順で検出されます。同じ実体パスを指すルートは重複排除されます。異なるディレクトリに同名のスキルがある場合は、先に検出したルートが優先され、プラグインが警告を記録します。Codex自体は、異なるスコープに同名のスキルがある構成も許容します。
Tip
Claude CodeとCodexで同じスキルを一元管理するには、ソースを1か所に置き、そのスキルディレクトリを.claude/skills/と.codex/skills/の両方からシンボリックリンクします。
ミラー内のリポジトリ相対リンク
ミラーされたリソース本文では、リポジトリ内の相対パスを指すMarkdownリンクと画像をインラインコードに変換します。リンク先をドキュメントのURLとして扱うと壊れるためです。リンクのラベルまたは画像の代替テキストを表示します。Claude側のCLAUDE.md・コマンド・エージェント、Codex側のAGENTS.md、および両方のスキル本文とサブページに適用されます。
スキルのメイン本文にあるreferences/・scripts/・assets/へのリンクは、対応するサブページが実際に生成される場合に限り、そのページへのリンクとして維持されます。存在しない対象や生成対象外のファイル（.shスクリプトなど）はインラインコードになります。サブページ本文のリポジトリ相対リンクもインラインコードになります。生成ページへのリンクを維持する例外は、スキルのメイン本文に適用されます。
外部URL、ルート相対URL、ページ内フラグメントは維持されます。インラインコードやコードフェンス内のリンク例は変換しません。通常の手書きMDXでは、引き続きドキュメント間リンクの規則に従ってください。