# zudo-doc

> Documentation base framework built with Astro and MDX.

---

# はじめに

> Source: /pj/zudo-doc/ja/docs/getting-started

「はじめに」セクションへようこそ。以下のトピックから始めましょう。

---

# 0.1.0

> Source: /pj/zudo-doc/ja/docs/changelog/0.1.0

zudo-docの初回リリース。

### 機能

- Astro 6とMDXコンテンツコレクション
- 16色パレットによるTailwind CSS v4デザイントークンシステム
- ファイル構造からの自動生成ツリーによるサイドバーナビゲーション
- i18nサポート（英語・日本語）
- アドモニションコンポーネント（Note、Tip、Info、Warning、Danger）
- Shikiによるコードハイライト
- スクロールスパイ付き目次
- 複数の組み込みテーマによるカラースキーム切り替え
- 検索機能

---

# 基本コンポーネント

> Source: /pj/zudo-doc/ja/docs/components/basic-components

zudo-docのデザイントークンシステムによってスタイリングされた、標準的なMarkdownおよびMDX要素です。インポートは不要です。

## 見出し

`h2` から `h4` までの見出しは、目次サイドバーに表示されます。

### 見出し3

#### 見出し4

```mdx
## 見出し2
### 見出し3
#### 見出し4
```

## テキストの書式

**太字テキスト**、*イタリックテキスト*、~~取り消し線~~。組み合わせも可能です：***太字かつイタリック***。

```mdx
**太字テキスト**、*イタリックテキスト*、~~取り消し線~~。
組み合わせも可能です：***太字かつイタリック***。
```

## インラインコード

バッククォートを使って、文中に `インラインコード` を挿入できます。

```mdx
バッククォートを使って、文中に `インラインコード` を挿入できます。
```

## コードブロック

フェンスドコードブロックはShikiによるシンタックスハイライトに対応しています。開始バッククォートの後に言語を指定します。

```ts
function greet(name: string): string {
  return `Hello, ${name}!`;
}
```

````mdx
```ts

function greet(name: string): string {
  return `Hello, ${name}!`;
}

```
````

### サポートされている言語

Shikiは幅広い言語をサポートしています。代表的なものは以下の通りです：

| 言語 | 識別子 |
| -------- | ---------- |
| TypeScript | `ts`, `typescript` |
| JavaScript | `js`, `javascript` |
| HTML | `html` |
| CSS | `css` |
| JSON | `json` |
| Bash / Shell | `bash`, `sh`, `shell`, `zsh` |
| Markdown | `md`, `markdown` |
| MDX | `mdx` |
| YAML | `yaml`, `yml` |
| Python | `python`, `py` |
| Rust | `rust`, `rs` |
| Go | `go` |
| SQL | `sql` |
| GraphQL | `graphql` |
| Diff | `diff` |
| TOML | `toml` |
| Astro | `astro` |
| JSX / TSX | `jsx`, `tsx` |

すべての利用可能な識別子については、[サポートされている言語の一覧](https://shiki.style/languages)を参照してください。

## 箇条書きリスト

- 1つ目の項目
- 2つ目の項目
  - ネストされた項目
  - もう1つのネストされた項目
    - 深いネスト
- 3つ目の項目

```mdx
- 1つ目の項目
- 2つ目の項目
  - ネストされた項目
  - もう1つのネストされた項目
    - 深いネスト
- 3つ目の項目
```

## 番号付きリスト

1. ステップ1
2. ステップ2
1. サブステップ1
2. サブステップ2
3. ステップ3

```mdx
1. ステップ1
2. ステップ2
   1. サブステップ1
   2. サブステップ2
3. ステップ3
```

## 引用

> これは引用ブロックです。複数行にまたがることができ、
> 内部で**書式付きテキスト**も使用できます。

```mdx
> これは引用ブロックです。複数行にまたがることができ、
> 内部で**書式付きテキスト**も使用できます。
```

## テーブル

| 機能       | 状態        | 備考               |
| ---------- | ----------- | ------------------ |
| MDX        | サポート済み | `@astrojs/mdx` 経由 |
| Shiki      | 組み込み     | コードハイライト    |
| Tailwind   | v4          | トークンベースの設計 |

```mdx
| 機能       | 状態        | 備考               |
| ---------- | ----------- | ------------------ |
| MDX        | サポート済み | `@astrojs/mdx` 経由 |
| Shiki      | 組み込み     | コードハイライト    |
| Tailwind   | v4          | トークンベースの設計 |
```

## リンク

内部リンク：[はじめに](/ja/docs/getting-started)

外部リンク：[Astroドキュメント](https://docs.astro.build)

```mdx
内部リンク：[はじめに](/ja/docs/getting-started)

外部リンク：[Astroドキュメント](https://docs.astro.build)
```

## 水平線

3つのダッシュで水平線を作成できます：

---

```mdx
---
```

---

# 開発

> Source: /pj/zudo-doc/ja/docs/develop

zudo-doc自体の開発メモ。

---

# はじめに

> Source: /pj/zudo-doc/ja/docs/getting-started/introduction

**zudo-doc** へようこそ — AstroとMDXで構築されたドキュメントベースフレームワークです。

## なぜ zudo-doc？

- **高速な開発サーバー** — Vite搭載、ページはオンデマンドでコンパイル
- **MDXサポート** — JSXコンポーネントでドキュメントを記述
- **Tailwind CSS** — ユーティリティファーストのスタイリング
- **静的エクスポート** — 純粋なHTMLを生成、デフォルトでJSゼロ
- **llms.txt** — AI利用可能なドキュメントファイルを自動生成
- **バージョニング** — バージョンプレフィックス付きURLで複数バージョンのドキュメントを管理
- **最小限のベース** — 独自のコンポーネントで拡張可能

## クイックスタート

```bash
pnpm create zudo-doc my-docs
cd my-docs
pnpm install
pnpm dev
```

[http://localhost:4321](http://localhost:4321) を開いてドキュメントを確認してください。CLIのオプションやセットアップの詳細は[インストール](/ja/docs/getting-started/installation/)ガイドをご覧ください。

ショーケースドキュメントを含むフルプロジェクトを確認したい場合は、リポジトリを直接クローンしてください：

```bash
git clone https://github.com/zudolab/zudo-doc.git my-docs
cd my-docs
pnpm install
pnpm dev
```

---

# 設定

> Source: /pj/zudo-doc/ja/docs/guides/configuration

zudo-docは`src/config/`ディレクトリ内の少数のファイルとルートの`astro.config.ts`で設定を行います。

## サイト設定

メインの設定ファイルは`src/config/settings.ts`です：

```ts

  colorScheme: "Default Dark",
  colorMode: {
    defaultMode: "light",
    lightScheme: "Default Light",
    darkScheme: "Default Dark",
    respectPrefersColorScheme: true,
  },
  siteName: "zudo-doc",
  siteDescription: "Documentation base framework...",
  base: "/",
  trailingSlash: false,
  docsDir: "src/content/docs",
  locales: {
    ja: { label: "JA", dir: "src/content/docs-ja" },
  },
  mermaid: true,
  noindex: false,
  editUrl: false,
  siteUrl: "",
  sitemap: true,
  designTokenPanel: true,
  docMetainfo: true,
  docTags: true,
  frontmatterPreview: {},
  math: true,
  docHistory: true,
  claudeResources: {
    claudeDir: ".claude",
  },
  headerNav: [
    { label: "Getting Started", labelKey: "nav.gettingStarted", path: "/docs/getting-started", categoryMatch: "getting-started" },
    { label: "Guides", labelKey: "nav.guides", path: "/docs/guides", categoryMatch: "guides" },
    { label: "Reference", labelKey: "nav.reference", path: "/docs/reference", categoryMatch: "reference" },
    { label: "Claude", labelKey: "nav.claude", path: "/docs/claude", categoryMatch: "claude" },
  ],
};
```

### colorScheme

アクティブなカラースキーム名。`src/config/color-schemes.ts`のキーと一致する必要があります。

利用可能な組み込みスキーム：**Default Light**、**Default Dark**。`src/config/color-schemes.ts`でカスタムスキームを追加できます。

利用可能なスキームの一覧、プレビュー、カスタムスキームの追加手順については[カラーガイド](/ja/docs/reference/color)を参照してください。

### colorMode

ライト/ダークモードの動作を設定します。カラーモード切り替えを完全に無効にして`colorScheme`で指定されたスキームのみを使用するには`false`に設定します。

有効にすると、`ColorModeConfig`オブジェクトを受け入れます：

| プロパティ | 型 | 説明 |
|----------|------|-------------|
| `defaultMode` | `"light"` \| `"dark"` | ユーザー設定が適用される前の初期カラーモード |
| `lightScheme` | string | ライトモードで使用するカラースキーム名 |
| `darkScheme` | string | ダークモードで使用するカラースキーム名 |
| `respectPrefersColorScheme` | boolean | `true`の場合、ユーザーのOS設定のライト/ダーク設定に自動的に一致 |

```ts
colorMode: {
  defaultMode: "light",
  lightScheme: "Default Light",
  darkScheme: "Default Dark",
  respectPrefersColorScheme: true,
},
// またはカラーモード切り替えを無効化:
colorMode: false,
```

### base

サブディレクトリにデプロイする際のベースパス。サイトがルートドメインではなくサブパスから配信される場合に設定します。

デフォルト：`"/"`

例えば、サイトを`https://example.com/my-docs/`で配信する場合：

```ts
base: "/my-docs",
```

すべての内部リンク（サイドバー、ナビゲーション、前後ページ、検索）にはベースパスが自動的にプレフィックスされます。これは[AstroのConfigの`base`オプション](https://docs.astro.build/en/reference/configuration-reference/#base)に直接マッピングされます。

MDXコンテンツ内のインラインMarkdownリンク（例：`[リンクテキスト](/docs/some-page)`）は自動的に書き換えられません。ルート以外のbaseを使用する場合は、コンテンツファイル内で相対リンクを使用してください。

### trailingSlash

URLの末尾にトレイリングスラッシュを付けるかどうかを制御します。`true`の場合、すべての内部リンクがトレイリングスラッシュ付きで生成されます（例：`/docs/guides`ではなく`/docs/guides/`）。これにより、Astroの[`trailingSlash`](https://docs.astro.build/en/reference/configuration-reference/#trailingslash)も`"always"`または`"never"`に設定されます。

デフォルト：`false`

```ts
trailingSlash: true,
```

一部のホスティングプラットフォーム（AWS Amplify、Cloudflare Pagesなど）ではトレイリングスラッシュを有効にした方がうまく動作します。ページ遷移時に404エラーが発生する場合は、`true`に設定してみてください。

有効にすると、ミドルウェアがトレイリングスラッシュなしのURLをトレイリングスラッシュ付きのURLへ**301リダイレクト**します（例：`/docs/guides` → `/docs/guides/`）。Astroの開発サーバーはこのリダイレクトを自動的に行わないため、開発時でも一貫したURLを保証します。静的アセット（`.js`、`.css`、`.png`などの拡張子を持つファイル）やAstro内部パス（`/_astro/`、`/_image`）はリダイレクトの対象外です。

### onBrokenMarkdownLinks

ビルド中に壊れた内部マークダウンリンクをどのように処理するかを制御します。zudo-docのリンクリゾルバープラグインが解決する相対 `[テキスト](./page.mdx)` リンクに適用されます。

- `"warn"` — 警告をログに出力しますが、ビルドは継続します
- `"error"` — エラーをスローしてビルドを失敗させます
- `"ignore"` — 壊れたリンクを出力なしで無視します

型：`"warn" | "error" | "ignore"`

デフォルト：`"warn"`

```ts
onBrokenMarkdownLinks: "error", // 壊れたリンクでビルドを失敗させる
```

### docsDir

英語ドキュメントのMDXファイルが格納されるディレクトリパス（プロジェクトルートからの相対パス）。Astroの`glob()`ローダーを使用するため、任意のディレクトリを指定できます。

デフォルト：`"src/content/docs"`

```ts
docsDir: "docs",  // プロジェクトルートの./docs/にコンテンツを配置
```

これはDocusaurusの`docs.path`オプションに似ています — zudo-docをドキュメントがプロジェクトルートレベルにある大規模プロジェクトのドキュメントツールとして使用する場合に便利です。

### locales

追加ロケール設定のマップ。各キーはロケールコードで、値は`label`（言語切り替えの表示名）と`dir`（コンテンツディレクトリパス）を持つオブジェクトです。

デフォルト：`{}`

```ts
locales: {
  ja: { label: "JA", dir: "src/content/docs-ja" },
  ko: { label: "KO", dir: "src/content/docs-ko" },
},
```

各ロケールエントリに対して、zudo-docは自動的に：

- Astroコンテンツコレクション（`docs-{code}`）を作成
- Astroのi18nルーティングにロケールを登録
- 言語切り替えに追加

### versions

マルチバージョンドキュメントを設定します。`VersionConfig`オブジェクトの配列を設定すると、zudo-docはバージョン管理されたコンテンツコレクションを作成し、サイドバーにバージョン切り替えを追加します。各バージョンのセクションは`/v/{slug}/docs/`でアクセスできます。バージョン管理を無効にするには`false`を設定します。

型：`VersionConfig[] | false`

デフォルト：`false`

各`VersionConfig`オブジェクトは以下のプロパティを受け入れます：

| プロパティ | 型 | 説明 |
|----------|------|-------------|
| `slug` | string | URLパスに使用するバージョン識別子（例：`"1.0"`、`"v1"`） |
| `label` | string | バージョン切り替えに表示されるラベル（例：`"1.0.0"`） |
| `docsDir` | string | このバージョンの英語ドキュメントのコンテンツディレクトリパス |
| `locales` | Record（オプション） | このバージョンのロケール別コンテンツディレクトリ（`{ ja: { dir: "..." } }`） |
| `banner` | `"unmaintained"` \| `"unreleased"` \| `false`（オプション） | このバージョンのすべてのページに表示されるバナー |

```ts
versions: [
  {
    slug: "1.0",
    label: "1.0.0",
    docsDir: "src/content/docs-v1",
    banner: "unmaintained",
  },
],
// またはバージョン管理を無効化:
versions: false,
```

バージョン切り替えの仕組みやメンテナンス終了・未リリースバージョンのバナー設定については[バージョン管理ガイド](/ja/docs/guides/versioning)を参照してください。

### siteName

ヘッダーに表示され、ページタイトルに使用されるサイト名。ページタイトルは`{ページタイトル} | {siteName}`の形式になります。

### siteDescription

サイトの短い説明。SEOやソーシャルシェアリングのメタタグに使用されます。

デフォルト：`""`

### siteUrl

サイトの完全なベースURL（例：`"https://example.com"`）。サイトマップでの絶対URL生成に必要です。

デフォルト：`""`

### noindex

`true`の場合、すべてのページに`noindex`と`nofollow`メタタグを追加します。検索エンジンにインデックスされるべきでない内部ドキュメントサイトに便利です。

デフォルト：`false`

### mermaid

Mermaidダイアグラムのサポートを有効にします。`true`の場合、`mermaid`言語識別子を持つフェンスコードブロックがダイアグラムとしてレンダリングされます。`false`の場合、mermaidコードブロックはプレーンコードとして表示されます。

デフォルト：`true`

### math

KaTeX数式レンダリングを有効にします。`true`の場合、インライン数式（`$...$`）、ブロック数式（`$$...$$`）、およびフェンス`math`コードブロックが数式としてレンダリングされます。

デフォルト：`true`

### cjkFriendly

CJKフレンドリーなタイポグラフィ調整を有効にします。`true`の場合、ドキュメント全体の中国語、日本語、韓国語テキストに対して改善された改行およびワードラップの動作を適用します。

型：`boolean`

デフォルト：`false`

```ts
cjkFriendly: true,
```

### editUrl

「このページを編集」リンクのベースURL。完全なURLは`editUrl + contentDir + "/" + entryId`として構築されます。編集リンクを無効にするには`false`に設定します。

デフォルト：`false`（無効）

```ts
editUrl: "https://github.com/my-org/my-repo/edit/main/",
// または無効化:
editUrl: false,
```

### sitemap

ビルド時に自動`sitemap.xml`生成を有効にします。サイトマップには404を除くすべてのビルド済みHTMLページが含まれます。

デフォルト：`true`

### llmsTxt

ビルド時に自動`llms.txt`生成を有効にします。`true`の場合、すべてのドキュメントページをタイトルと説明とともにリスト化した`llms.txt`ファイルがサイトルートに生成されます。このファイルは[llms.txt仕様](https://llmstxt.org/)に従っており、AIアシスタントがドキュメントコンテンツを発見・インデックス化するのに役立ちます。

型：`boolean`

デフォルト：`false`

```ts
llmsTxt: true,
```

### docMetainfo

ページタイトルの下にメタデータ（作成日、最終更新日、著者）を表示します。日付と著者はビルド時にgit履歴から抽出されます。

デフォルト：`true`

### docTags

ドキュメントページのタグサポートを有効にします。`true`の場合、ページは`tags`フロントマターフィールドを使用でき、タグインデックスページが`/docs/tags/`に生成されます。

詳しい使い方は[タグガイド](./tags.mdx)を参照してください。

デフォルト：`true`

### tagPlacement

ドキュメントページに表示されるタグバッジ列の位置を制御します。

型：`"after-title" | "before-pager"`

デフォルト：`"after-title"`

- `"after-title"` — ページタイトルの直下、本文の上にバッジ列を表示します。
- `"before-pager"` — コンテンツの末尾、前後ページャーのすぐ上にバッジ列を表示します。

```ts
tagPlacement: "before-pager",
```

`docTags` が `false` の場合、またはページにタグが付いていない場合は効果がありません。

### frontmatterPreview

カスタムフロントマターフィールドをページタイトルの直下にコンパクトなキー/値テーブルとして表示します。フレームワーク管理のキー（`title`、`description`、`sidebar_position` など）はデフォルトで非表示になるため、プロジェクト固有のメタデータのみが表示されます。すべてのページでブロックを無効にするには `false` を設定します。

型：`FrontmatterPreviewConfig | false`

デフォルト：`{}`（組み込み無視リストで有効）

`FrontmatterPreviewConfig` オブジェクトは以下を受け入れます：

| プロパティ | 型 | 説明 |
|----------|------|-------------|
| `ignoreKeys` | `string[]`（オプション） | デフォルトの無視リストを完全に置き換えます。設定すると `extraIgnoreKeys` は無視されます |
| `extraIgnoreKeys` | `string[]`（オプション） | デフォルトに加えて無視する追加キーです。`ignoreKeys` が設定されている場合は効果がありません |

```ts
// Extend the default list:
frontmatterPreview: {
  extraIgnoreKeys: ["reviewed_by", "internal_id"],
},
// Replace the default list entirely:
frontmatterPreview: {
  ignoreKeys: ["title", "description", "sidebar_position"],
},
// Disable:
frontmatterPreview: false,
```

完全なデフォルト無視リストとライブデモについては、[フロントマタープレビューリファレンス](../reference/frontmatter-preview.mdx) を参照してください。

### designTokenPanel

インタラクティブなDesign Token Panelを有効にします。`true`の場合、ヘッダーにパレットアイコンが表示され、タブ型のパネルを開いてスペーシング・フォント・サイズ・カラーの各トークンをリアルタイムで編集できます。変更は`localStorage`に保存され、JSONとしてエクスポート／インポートできます。

デフォルト：`false`（`true`に設定して有効化）

4つのタブ構成やJSONエクスポートワークフロー、非推奨エイリアス`colorTweakPanel`については[Design Token Panelリファレンス](../reference/design-token-panel.mdx)を参照してください。

### aiAssistant

AIアシスタントチャットウィジェットを有効にします。`true`の場合、ページにチャットボタンが表示され、ドキュメントに関する質問に答えるAI搭載のアシスタントが開きます。設定済みの`ai-chat-worker` Cloudflare Workerバックエンドが必要です。

型：`boolean`

デフォルト：`false`

```ts
aiAssistant: true,
```

### sidebarToggle

サイドバー折り畳みトグルを有効にします。`true`の場合、サイドバーヘッダーのボタンでユーザーがサイドバーを完全に折り畳むことができ、コンテンツの水平スペースが広がります。折り畳み状態は`localStorage`に保存されます。

型：`boolean`

デフォルト：`false`

```ts
sidebarToggle: true,
```

### sidebarResizer

サイドバー幅のリサイズを有効にします。`true`の場合、サイドバーの右端にドラッグハンドルが表示され、ユーザーがサイドバー幅をドラッグして調整できます。リサイズ後の幅は`localStorage`に保存されます。

型：`boolean`

デフォルト：`false`

```ts
sidebarResizer: true,
```

### docHistory

ドキュメントごとのgitリビジョン履歴ビューアを有効にします。`true`の場合、各ドキュメントページに**History**ボタンが表示され、ドキュメントのgitコミット履歴と行単位のdiffビューアを備えたサイドパネルが開きます。

開発モードでは、履歴はポート4322で動作するスタンドアロンの`@zudo-doc/doc-history-server`パッケージが配信します。本番環境では、CLIジェネレーターがCI中に静的JSONファイルを生成します。サーバーとCLIの詳細については[Doc History Serverリファレンス](/ja/docs/reference/doc-history-server)を参照してください。

デフォルト：`false`（`true`に設定して有効化）

使用方法の詳細、キーボードショートカット、技術情報については[ドキュメント履歴ガイド](/ja/docs/guides/doc-history)を参照してください。

### htmlPreview

``コンポーネントのグローバル設定です。設定すると、指定した`head`、`css`、`js`がサイト上のすべての`` iframeに注入されます。共有フォント、デザインシステムのスタイルシート、ユーティリティスクリプトを各コンポーネントデモで繰り返すことなく読み込む際に便利です。

グローバル注入を無効にするには`undefined`（デフォルト）に設定します。

型：`HtmlPreviewConfig | undefined`

デフォルト：`undefined`

`HtmlPreviewConfig`オブジェクトは以下のプロパティを受け入れます：

| プロパティ | 型 | 説明 |
|----------|------|-------------|
| `head` | string（オプション） | ``に注入される生のHTML（例：フォントやアイコンライブラリの``タグ） |
| `css` | string（オプション） | プリフライトリセット後に``ブロックとして注入されるCSS |
| `js` | string（オプション） | ``の前に``ブロックとして注入されるJavaScript |

```ts
htmlPreview: {
  head: ``,
  css: `body { font-family: sans-serif; }`,
  js: `console.log("HtmlPreview loaded")`,
},
// またはグローバル注入を無効化:
htmlPreview: undefined,
```

個々の``ブロックは、独自の`head`、`css`、または`js`プロパティを渡すことでグローバル設定を拡張できます — 値はグローバル設定に上書きではなく追加されます。

### claudeResources

Claude Codeリソースビューアを設定します。`.claude/`ディレクトリからドキュメントページを自動生成します。無効にするには`false`に設定します。

| プロパティ | 型 | 説明 |
|----------|------|-------------|
| `claudeDir` | string | `.claude`ディレクトリへのパス（プロジェクトルートからの相対パス） |
| `projectRoot` | string（オプション） | モノレポ設定用のプロジェクトルートオーバーライド |

```ts
claudeResources: {
  claudeDir: ".claude",
},
// または無効化:
claudeResources: false,
```

生成される内容と仕組みの詳細については[Claude Codeリソースガイド](/ja/docs/guides/claude-resources)を参照してください。

### footer

サイトフッターを設定します。`FooterConfig`オブジェクトを設定すると、リンク列とオプションの著作権テキストを含むフッターがレンダリングされます。フッターを完全に無効にするには`false`を設定します。

型：`FooterConfig | false`

デフォルト：`false`

`FooterConfig`オブジェクトは以下を受け入れます：

| プロパティ | 型 | 説明 |
|----------|------|-------------|
| `links` | `FooterLinkColumn[]` | フッターに表示されるリンク列の配列 |
| `copyright` | string（オプション） | 下部に表示される著作権テキスト。HTMLをサポート |

各`FooterLinkColumn`：

| プロパティ | 型 | 説明 |
|----------|------|-------------|
| `title` | string | 列の見出し |
| `items` | `FooterLinkItem[]` | この列のリンクの配列 |
| `locales` | Record（オプション） | ロケール別タイトルのオーバーライド（例：`{ ja: { title: "ドキュメント" } }`） |

各`FooterLinkItem`：

| プロパティ | 型 | 説明 |
|----------|------|-------------|
| `label` | string | リンクの表示テキスト |
| `href` | string | リンクURL |
| `locales` | Record（オプション） | ロケール別ラベルのオーバーライド（例：`{ ja: { label: "はじめに" } }`） |

```ts
footer: {
  links: [
    {
      title: "Docs",
      locales: { ja: { title: "ドキュメント" } },
      items: [
        { label: "Getting Started", href: "/docs/getting-started", locales: { ja: { label: "はじめに" } } },
      ],
    },
    {
      title: "Community",
      items: [{ label: "GitHub", href: "https://github.com/my-org/my-repo" }],
    },
  ],
  copyright: `Copyright © ${new Date().getFullYear()} Your Name.`,
},
// またはフッターを無効化:
footer: false,
```

### headerNav

サイトヘッダーバーにレンダリングされるナビゲーションリンクの配列。各アイテムは以下のプロパティをサポートします：

| プロパティ | 型 | 説明 |
|----------|------|-------------|
| `label` | string | ヘッダーに表示されるテキスト |
| `labelKey` | string（オプション） | 翻訳が利用可能な場合に`label`を上書きするi18n翻訳キー |
| `path` | string | リンク先のURLパス |
| `categoryMatch` | string（オプション） | このヘッダータブをサイドバーカテゴリにリンク |

```ts
headerNav: [
  { label: "Getting Started", labelKey: "nav.gettingStarted", path: "/docs/getting-started", categoryMatch: "getting-started" },
  { label: "Guides", labelKey: "nav.guides", path: "/docs/guides", categoryMatch: "guides" },
  { label: "Reference", labelKey: "nav.reference", path: "/docs/reference", categoryMatch: "reference" },
  { label: "Claude", labelKey: "nav.claude", path: "/docs/claude", categoryMatch: "claude" },
],
```

## Astro設定

ルートの`astro.config.ts`がビルドパイプラインを制御します：

```ts

  output: "static",
  integrations: [mdx(), react(), searchIndexIntegration()],
  i18n: {
    defaultLocale: "en",
    locales: ["en", ...Object.keys(settings.locales)],
    routing: { prefixDefaultLocale: false },
  },
  vite: {
    plugins: [tailwindcss()],
  },
  markdown: {
    shikiConfig: { theme: shikiTheme },
  },
});
```

主なポイント：

- **output**：完全な静的HTMLエクスポートのため`"static"`に設定
- **integrations**：MDXサポート、Preactアイランド（compatモード）、MiniSearch検索インデックス
- **i18n**：英語（デフォルト、`/docs/...`）と日本語（`/ja/docs/...`）。デフォルトロケールにはURLプレフィックスなし
- **Tailwind CSS**：Astroインテグレーションではなく`@tailwindcss/vite`プラグイン経由でロード
- **Shikiテーマ**：アクティブなカラースキームの`shikiTheme`プロパティから自動的に導出 — 手動同期不要

Shikiコードハイライトテーマはカラースキームに紐づいています。設定で`colorScheme`を変更すると、シンタックスハイライトテーマも自動的に更新されます。

## ロゴ

サイトロゴはランディングページにマスクされたSVGシェイプとして表示されます。ファイルは`public/img/logo.svg`にあります。

デフォルトのロゴは[`@takazudo/kumiko-gen`](https://www.npmjs.com/package/@takazudo/kumiko-gen)で生成されたランダムな幾何学パターンです。新しいランダムパターンで再生成するには：

```bash
pnpm run generate:logo
```

`public/img/logo.svg`を任意のカスタムSVGファイルに置き換えることもできます。ロゴはアルファチャンネルを使ったCSSマスクとしてレンダリングされるため：

- SVGは**透明な背景が必須**です — 不透明な背景は塗りつぶされた矩形としてレンダリングされます
- SVGファイル内のストロークや塗りの色は関係ありません。表示色はサイトのカラートークンで制御されます

## カラースキーム設定

カラースキームは`src/config/color-schemes.ts`で定義されます。各スキームは22のカラープロパティと`shikiTheme`を提供します：

- `background`、`foreground`、`cursor`、`selectionBg`、`selectionFg`
- `palette` — 16色スロット（`palette[0]`から`palette[15]`）
- `shikiTheme` — シンタックスハイライト用の対応するShikiテーマ名
- `semantic`（オプション）— `surface`、`muted`、`accent`、`accentHover`のオーバーライド

カラースキームの追加やカスタマイズの詳細については[カラーガイド](/ja/docs/reference/color)を参照してください。

---

# ガイド

> Source: /pj/zudo-doc/ja/docs/guides

zudo-docの機能やカスタマイズについてのガイドです。

---

# デモ: サイドバー非表示

> Source: /pj/zudo-doc/ja/docs/guides/layout-demos/hide-sidebar

このページは`hide_sidebar: true`フロントマターオプションのデモです。左側のサイドバーが非表示になり、コンテンツが狭いコンテナに中央揃えで表示されます。

## 何が起きているか

このページでは左側のサイドバーナビゲーションが非表示になっています。使用しているフロントマターは以下の通りです：

```yaml
---
title: "デモ: サイドバー非表示"
hide_sidebar: true
hide_toc: false
---
```

## 目次は表示されたまま

右側の目次は引き続き表示され、このページのセクションにすばやくアクセスできます。左側のサイドバーのみが影響を受けます。

## モバイルナビゲーション

モバイルデバイスでは、ハンバーガーメニューから引き続きナビゲーションにアクセスできます。`hide_sidebar`オプションはデスクトップのサイドバーにのみ影響します。

## 使用場面

サイドバーナビゲーションが不要なページ（スタンドアロンの記事、ランディングページ、集中して読むコンテンツなど）で`hide_sidebar: true`を使用します。

詳しくは[フロントマターリファレンス](/ja/docs/guides/frontmatter/#hide_sidebar)をご覧ください。

## 関連ページ

- [目次非表示](/ja/docs/guides/layout-demos/hide-toc/) — 右側の目次を非表示にします
- [サイドバー＆目次非表示](/ja/docs/guides/layout-demos/hide-both/) — 両方のパネルを非表示にします

---

# デザインシステム

> Source: /pj/zudo-doc/ja/docs/reference/design-system

zudo-docは**タイトトークン戦略**を採用しています。Tailwindフレームワーク全体をインポートするのではなく、`preflight`と`utilities`のみを読み込み、デフォルトテーマ層を完全にスキップします。小さく意図的なデザイントークンのセットをゼロから定義します。このページでは、スペーシング、タイポグラフィ、カラー、角丸、ブレークポイントの全体像を解説します。

## タイトトークン戦略

Tailwind CSSには数百の組み込み値（カラー、スペーシングスケール、フォントサイズなど）が用意されています。テーマ切り替え可能なプロジェクトでは、これらのデフォルト値が問題を引き起こします。ハードコードされた値はテーマ変更を無視し、一貫性を崩します。

zudo-docでは`src/styles/global.css`内で選択的インポートを使い、`preflight`（リセット）と`utilities`（ユーティリティクラス）のみを読み込んでいます。デフォルトテーマ層は完全にスキップされます:

```css
@import "tailwindcss/preflight";
@import "tailwindcss/utilities";

@theme {
  /* 必要なものだけを定義 — リセットは不要 */
  --color-bg: var(--zd-bg);
  --color-fg: var(--zd-fg);
  /* ... */
}
```

デフォルトテーマが読み込まれないため、`--*: initial`によるリセットブロックは不要です。`@theme`内で明示的に定義されたトークンのみが機能します。未定義のトークン（`p-4`や`bg-gray-500`など）を使っても効果はありません。値自体が存在しないためです。これにより**無効なトークンはビルドエラーやスタイル欠落として現れ、視覚的なバグにはなりません**。

これが核となる設計思想です。プロジェクトに必要なものだけを定義する。システム内のすべての値は意図的であり、Tailwindデフォルトの誤使用はすぐに判明します。

## スペーシング

zudo-docではスペーシングを**水平（hsp）**と**垂直（vsp）**の2軸に分離しています。レイアウトにおいてそれぞれ異なる役割を果たすためです。水平スペーシングはインラインのリズムやガターを制御し、垂直スペーシングはコンテンツの流れやセクション間の余白を制御します。垂直スケールは大きいサイズほど広がり、コンテンツにより多くの余白を与えます。

### 水平スペーシング（hsp）

| トークン | 値 | 使用例 |
|-------|-------|---------------|
| `hsp-2xs` | `0.25rem` (4px) | `px-hsp-2xs` |
| `hsp-xs` | `0.375rem` (6px) | `px-hsp-xs` |
| `hsp-sm` | `0.5rem` (8px) | `gap-x-hsp-sm` |
| `hsp-md` | `0.75rem` (12px) | `px-hsp-md` |
| `hsp-lg` | `1rem` (16px) | `px-hsp-lg` |
| `hsp-xl` | `1.5rem` (24px) | `px-hsp-xl` |
| `hsp-2xl` | `2rem` (32px) | `px-hsp-2xl` |

### 垂直スペーシング（vsp）

| トークン | 値 | 使用例 |
|-------|-------|---------------|
| `vsp-2xs` | `0.25rem` (4px) | `py-vsp-2xs` |
| `vsp-xs` | `0.5rem` (8px) | `py-vsp-xs` |
| `vsp-sm` | `0.75rem` (12px) | `gap-y-vsp-sm` |
| `vsp-md` | `1rem` (16px) | `py-vsp-md` |
| `vsp-lg` | `1.5rem` (24px) | `py-vsp-lg` |
| `vsp-xl` | `2rem` (32px) | `py-vsp-xl` |
| `vsp-2xl` | `3rem` (48px) | `py-vsp-2xl` |

両軸とも`0`（`0px`）と`px`（`1px`）のユーティリティ値も含まれます。

```html
<!-- 水平パディング + 垂直パディング -->
非対称なスペーシングのコンテンツ

<!-- 2軸ギャップのグリッド -->
グリッドアイテム
```

`hsp-lg`は`1rem`ですが`vsp-lg`は`1.5rem`と、垂直軸は大きいサイズほど広がります。これは意図的な設計です。垂直方向の流れには水平方向のリズムより多くの余白が必要です。

## タイポグラフィ

### フォントサイズ

| トークン | 値 | 使用例 |
|-------|-------|---------|
| `caption` | `0.75rem` / 12px | `text-caption` |
| `small` | `0.875rem` / 14px | `text-small` |
| `body` | `1rem` / 16px | `text-body` |
| `subheading` | `1.125rem` / 18px | `text-subheading` |
| `heading` | `1.875rem` / 30px | `text-heading` |
| `display` | `3.75rem` / 60px | `text-display` |

### フォントウェイト

| トークン | 値 | 使用例 |
|-------|-------|---------|
| `normal` | `400` | `font-normal` |
| `medium` | `500` | `font-medium` |
| `semibold` | `600` | `font-semibold` |
| `bold` | `700` | `font-bold` |

### 行の高さ

| トークン | 値 | 使用例 |
|-------|-------|---------|
| `tight` | `1.25` | `leading-tight` |
| `snug` | `1.375` | `leading-snug` |
| `normal` | `1.5` | `leading-normal` |
| `relaxed` | `1.625` | `leading-relaxed` |

### フォントファミリー

| トークン | スタック | 使用例 |
|-------|-------|---------|
| `sans` | システムサンセリフスタック | `font-sans` |
| `mono` | システムモノスペーススタック | `font-mono` |

```html
ページタイトル
本文テキスト
インラインコード
```

## 角丸（Border Radius）

| トークン | 値 | 使用例 |
|-------|-------|---------|
| `DEFAULT` | `0.25rem` (4px) | `rounded` |
| `lg` | `0.5rem` (8px) | `rounded-lg` |
| `full` | `9999px` | `rounded-full` |

```html
デフォルトの角丸
大きめの角丸のカード
ピルバッジ
```

## ブレークポイント

| トークン | 値 | 使用例 |
|-------|-------|---------|
| `sm` | `640px` | `sm:flex` |
| `lg` | `1024px` | `lg:grid-cols-2` |
| `xl` | `1280px` | `xl:max-w-5xl` |

```html

  レスポンシブな水平パディング

```

## カラー

カラーは**3層戦略**を採用しています。生のパレット値（Tier 1）がセマンティックトークン（Tier 2）に流れ込み、さらにコンポーネントスコープのトークン（Tier 3）に供給されます。各層は上の層のみを参照するため、カラースキームを切り替えるとサイト全体が一括で更新されます。

カラートークンシステム、カラースキーム、カスタマイズの詳細は[カラーリファレンス](/ja/docs/reference/color)を参照してください。

## 使用ルール

Tailwindのデフォルトテーマはインポートされていません。`tailwindcss/preflight`と`tailwindcss/utilities`のみが読み込まれます。プロジェクトで定義されたトークンのみが機能します。

### 推奨

```html
<!-- セマンティックカラートークン -->
メインテキスト
パネル
リンク

<!-- スペーシングトークン -->
適切なスペーシング
グリッドギャップ

<!-- タイポグラフィトークン -->
見出し
```

### 非推奨

```html
<!-- NG: Tailwindデフォルト — 未定義で何も表示されない -->
表示されない

<!-- NG: ハードコードされたhex — テーマ切り替えで壊れる -->
テーマ切り替え時に壊れる
```

すべてのトークンは`src/styles/global.css`で定義されています。このファイルがデザインシステムの唯一の情報源です。

## インタラクションのルール

### リンクには hover:underline

_遷移する_ 要素（``、またはリンクとして振る舞う要素）は、ホバー時とキーボードフォーカス時にアンダーラインを表示します。ボタン、トグル、コントロールは対象外で、ボーダー／背景の変化で代替します。

**OK**（ナビゲーション用のリンク）：

```html
リンク
サイドバー項目
```

**NG**（focus-visible が欠けている）：

```html
<!-- NG: マウスだけ下線、キーボード操作では出ない -->
キーボードフォーカスで下線が出ない
```

**NG**（コントロール）：

```html
<!-- NG: ボタンは下線ではなくボーダー／背景ホバーを使う -->
代わりに hover:bg-accent/10 などを使う
```

`hover:underline focus-visible:underline` のペアが正規形です。必ず両方を書き、片方だけにはしないでください。実装例：`src/components/header.astro`、`src/components/site-tree-nav.tsx`、`src/components/footer.astro`。

より深い背景（ライト／ダークのコントラスト、下線だけで足りるか色の変化も必要か）は、ローカルの `/css-wisdom` スキルを参照してください。light-mode/dark-mode と three-tier トークン戦略のセクションがトレードオフを扱っています。

---

# /CLAUDE.md

> Source: /pj/zudo-doc/ja/docs/claude-md/root

**パス:** `CLAUDE.md`

# zudo-doc

Astro 6、MDX、Tailwind CSS v4、Preactアイランドで構築された最小限のドキュメントフレームワーク。

## Tech Stack

- **Astro 6** — Content Collectionsを使用した静的サイトジェネレーター
- **MDX** — `@astrojs/mdx`経由、`docsDir`設定でコンテンツディレクトリを構成可能
- **Tailwind CSS v4** — `@tailwindcss/vite`経由（`@astrojs/tailwind`ではない）
- **Preact** — インタラクティブなアイランド専用（TOCスクロールスパイ、サイドバートグル、折りたたみカテゴリ）、React API互換のcompatモードで動作
- **Shiki** — 組み込みコードハイライト、アクティブなカラースキームからテーマを設定
- **TypeScript** — `astro/tsconfigs/strict`による厳格モード

## Commands

- `pnpm dev` — ポート4321の開発サーバー（predevがステイルプロセスをキル）
- `pnpm build` — `dist/`への静的HTMLエクスポート
- `pnpm check` — Astro型チェック

## Key Directories

```
src/
├── components/          # Astro + Preactコンポーネント
│   └── admonitions/     # Note, Tip, Info, Warning, Danger
├── config/              # 設定、カラースキーム
├── content/
│   ├── docs/            # 英語MDXコンテンツ
│   └── docs-ja/         # 日本語MDXコンテンツ（docs/のミラー）
├── hooks/               # Preactフック（スクロールスパイ）
├── layouts/             # Astroレイアウト（doc-layout）
├── pages/               # ファイルベースルーティング
│   ├── docs/[...slug]   # 英語ドキュメントルート
│   └── ja/docs/[...slug] # 日本語ドキュメントルート
└── styles/
    └── global.css       # デザイントークン（@theme）& Tailwind設定
```

## Conventions

### Components: Astro vs Preact

- デフォルトで**Astroコンポーネント**（`.astro`）を使用 — JSゼロ、サーバーレンダリング
- **Preactアイランド**（`client:load`）はクライアントサイドのインタラクティビティが必要な場合のみ使用
- Preactはcompatモード（`@astrojs/preact` + `compat: true`）で動作し、React形式のインポートやAPIが使用可能
- 現在のPreactアイランド：`toc.tsx`、`mobile-toc.tsx`、`sidebar-toggle.tsx`、`sidebar-tree.tsx`、`theme-toggle.tsx`、`doc-history.tsx`、`color-tweak-panel.tsx`、`color-tweak-export-modal.tsx`

### Content Collections

- スキーマは`src/content.config.ts`で定義（Zodバリデーション）
- Astro 5の`glob()`ローダーを使用、設定からの構成可能な`base`ディレクトリ
- コンテンツディレクトリ：`docsDir`（デフォルト：`src/content/docs`）、`docsJaDir`（デフォルト：`src/content/docs-ja`）
- 必須フロントマター：`title`（string）
- オプション：`description`、`sidebar_position`（number）、`category`
- サイドバー順序は`sidebar_position`で決定

### Admonitions

すべてのMDXファイルでインポート不要で使用可能（ドキュメントページでグローバル登録）：
``、``、``、``、`` — それぞれオプションの`title`プロパティを受け付けます。

### i18n

- 英語（デフォルト）：`/docs/...` — `docsDir`のコンテンツ（デフォルト：`src/content/docs`）
- 日本語：`/ja/docs/...` — `docsJaDir`のコンテンツ（デフォルト：`src/content/docs-ja`）
- `astro.config.ts`で`prefixDefaultLocale: false`として設定
- 日本語ドキュメントは英語のディレクトリ構造をミラーする必要あり

## Design Token System

16色パレットシステムを使用。

### Three-Tier Color Strategy

**Tier 1 — Palette**（`ColorSchemeProvider`が`:root`に注入）：

- `--zd-bg`、`--zd-fg`、`--zd-sel-bg`、`--zd-sel-fg`、`--zd-cursor`
- `--zd-0`から`--zd-15`（16パレットスロット）

**Tier 2 — Semantic tokens**（`global.css`の`@theme`、スキームごとに解決）：

- パレットアクセス：`p0`–`p15` → `bg-p0`、`text-p8`、`border-p1`など
- ベース：`bg`、`fg` → `bg-bg`、`text-fg`
- UI：`surface`、`muted`、`accent`、`accent-hover`、`sel-bg`、`sel-fg`
- コンテンツ：`code-bg`、`code-fg`、`success`、`danger`、`warning`、`info`

**Tier 3 — Component tokens**（特定のコンポーネントにスコープ）：

- コンテンツ：`.zd-content`の直接要素スタイリング、`global.css`内（Tier 2を消費）

各ティアは上位ティアのみを参照。

### Color Rules

- Tailwindデフォルトカラー（`bg-gray-500`、`text-blue-600`）は**絶対に使用しない** — `initial`にリセットされる
- **常に**プロジェクトトークンを使用：`text-fg`、`bg-surface`、`border-muted`、`text-accent`など
- 標準UIにはセマンティックトークン（`text-accent`、`bg-code-bg`、`text-danger`）を優先
- セマンティックトークンが適合しない場合のみパレットトークン（`p0`–`p15`）を使用

### Changing Scheme

- `src/config/settings.ts`の`colorScheme`を編集
- 利用可能：Dracula、Catppuccin Mocha、Nord、TokyoNight、Gruvbox Dark、Atom One Dark
- `src/config/color-schemes.ts`でスキームを追加（22カラープロパティ + `shikiTheme`）

## CSS

- Tailwind v4：`tailwindcss/preflight` + `tailwindcss/utilities`をインポート（デフォルトテーマなし）
- `--*: initial`リセット不要 — デフォルトテーマは単にインポートされない
- コンテンツタイポグラフィ：`global.css`の`.zd-content`クラス（proseプラグインなし — `:where()`セレクターでの直接要素スタイリング）

---

# アドモニション

> Source: /pj/zudo-doc/ja/docs/components/admonitions

アドモニションは重要な情報を強調するためのコールアウトブロックです。5種類すべてがグローバルに利用可能で、インポートは不要です。

## Note

:::note
これはNoteです。一般的な情報やヒントの表示に使用します。
:::

:::note[カスタムタイトル]
Noteは読者が見逃すべきでない重要な情報を強調するのに適しています。
:::

```mdx
:::note
これはNoteです。一般的な情報やヒントの表示に使用します。
:::

:::note[カスタムタイトル]
Noteは読者が見逃すべきでない重要な情報を強調するのに適しています。
:::
```

## Tip

:::tip
これはTipです。便利な提案やベストプラクティスの紹介に使用します。
:::

:::tip[便利なヒント]
キーボードショートカットを使うと作業を効率化できます。
:::

```mdx
:::tip
これはTipです。便利な提案やベストプラクティスの紹介に使用します。
:::

:::tip[便利なヒント]
キーボードショートカットを使うと作業を効率化できます。
:::
```

## Info

:::info
これはInfoブロックです。追加のコンテキストや背景情報の提供に使用します。
:::

:::info[豆知識]
この機能はバージョン2.0で導入されました。
:::

```mdx
:::info
これはInfoブロックです。追加のコンテキストや背景情報の提供に使用します。
:::

:::info[豆知識]
この機能はバージョン2.0で導入されました。
:::
```

## Warning

:::warning
これはWarningです。潜在的な問題や注意すべき点のフラグに使用します。
:::

:::warning[非推奨のお知らせ]
このAPIは次のメジャーバージョンで削除されます。新しいAPIへの移行をお願いします。
:::

```mdx
:::warning
これはWarningです。潜在的な問題や注意すべき点のフラグに使用します。
:::

:::warning[非推奨のお知らせ]
このAPIは次のメジャーバージョンで削除されます。新しいAPIへの移行をお願いします。
:::
```

## Danger

:::danger
これはDangerアラートです。データ損失や破壊的変更に関する重大な警告に使用します。
:::

:::danger[破壊的変更]
このコマンドを実行すると、すべてのデータが完全に削除されます。この操作は取り消せません。
:::

```mdx
:::danger
これはDangerアラートです。データ損失や破壊的変更に関する重大な警告に使用します。
:::

:::danger[破壊的変更]
このコマンドを実行すると、すべてのデータが完全に削除されます。この操作は取り消せません。
:::
```

## コンポーネント構文

上記のディレクティブ構文に加えて、JSXコンポーネント構文も使用できます。より細かい制御が必要な場合やカスタムレイアウトを構築する場合に便利です。

```mdx

デフォルトタイトルのNote。

カスタムタイトル付きのWarning。

```

コンポーネント構文は同じ5種類（`Note`、`Tip`、`Info`、`Warning`、`Danger`）とオプションの `title` プロップをサポートしています。

## プロップ

| プロップ | 型 | デフォルト | 説明 |
|------|------|---------|-------------|
| `title` | string | タイプ名（例："Note"） | デフォルトのタイトルテキストを上書き |

## カラーリファレンス

各アドモニションタイプは、ボーダーとタイトルの色にセマンティックカラートークンを使用しています：

| タイプ | カラートークン | 代表的な色 |
|------|------------|---------------|
| Note | accent | 青 |
| Tip | success | 緑 |
| Info | info | シアン |
| Warning | warning | 黄 |
| Danger | danger | 赤 |

---

# コンポーネント

> Source: /pj/zudo-doc/ja/docs/components

zudo-docで利用できるコンポーネントとコンテンツ機能を紹介します。

---

# ジェネレーターCLIテスト

> Source: /pj/zudo-doc/ja/docs/develop/generator-cli-testing

# ジェネレーターCLIテスト

`create-zudo-doc`ジェネレーターCLIは、さまざまな機能の組み合わせで新しいzudo-docプロジェクトを生成します。テストでは、各組み合わせがビルド・実行でき、正しいファイルと設定が生成されることを検証します。

2つのClaude Codeスキルでこのワークフローを自動化しています：

| スキル | 目的 |
|--------|------|
| `/l-generator-cli-tester ` | 単一の生成パターンをテスト |
| `/l-run-generator-cli-whole-test` | 全9パターンを実行し、バグを修正して検証 |

## テストパターン

各パターンは異なる機能の組み合わせを有効にします：

| パターン | 説明 |
|----------|------|
| `barebone` | すべてOFF — 最小構成 |
| `search` | 検索のみ有効 |
| `i18n` | i18nのみ有効 |
| `sidebar-filter` | サイドバーフィルターのみ有効 |
| `claude-resources` | Claude Resourcesのみ有効 |
| `design-token-panel` | Design Token Panelのみ有効（API使用） |
| `light-dark` | ライト・ダークカラースキームモード |
| `lang-ja` | デフォルト言語を日本語に設定 |
| `all-features` | すべてON |

## テストの実行

### 全テストスイート

全9パターンをエンドツーエンドで実行し、失敗を自動修正して検証します：

```
/l-run-generator-cli-whole-test
```

ヘッドレスブラウザによるレンダリングチェック付き：

```
/l-run-generator-cli-whole-test --headless
```

### 単一パターン

1つのパターンを個別にテストします：

```
/l-generator-cli-tester barebone
/l-generator-cli-tester all-features --headless
```

## 各テストのチェック内容

各パターンは以下のステップを実行します：

1. **スキャフォールド** — パターン固有のフラグでジェネレーターCLI（またはプログラマティックAPI）を実行
2. **インストール** — 生成されたプロジェクトで`pnpm install`
3. **ビルド** — `pnpm build`で静的エクスポートの成功を検証
4. **開発サーバー** — `pnpm dev`を起動し、8秒待ってプロセスがまだ実行中か確認
5. **ファイル検証** — 有効な機能に基づいて、期待されるファイルの存在/不在を確認
6. **設定検証** — 生成された`settings.ts`を読み、正しい値を確認
7. **ショーケース比較** — 生成されたコードをメインのzudo-docショーケースと比較
8. **ヘッドレスブラウザ**（`--headless`使用時） — 実際のブラウザでページをレンダリングし、JSエラーを確認、視覚要素（検索アイコン、言語切り替え、テーマトグルなど）を検証

## バグ修正ワークフロー

`/l-run-generator-cli-whole-test`スキルには構造化されたバグ修正フェーズがあります：

1. **フェーズ1** — 全9パターンを実行し、結果を収集
2. **フェーズ2** — 各失敗について：失敗ステップの診断、関連ソースファイルの確認、最小限の修正適用、CLIの再ビルドと再テスト、個別コミット
3. **フェーズ3** — 全9パターンを最初から再実行し、リグレッションがないことを確認
4. **フェーズ4** — サマリーレポートを出力

### よくある失敗パターン

| 失敗内容 | 原因 | 修正対象 |
|----------|------|----------|
| ビルド時にモジュールが見つからない | 生成された`package.json`に依存関係がない | `scaffold.ts` — `generatePackageJson()` |
| astro.configでインポートが見つからない | 機能のインテグレーションが含まれていない | `astro-config-gen.ts` |
| settings.tsの型エラー | 設定フィールドが不足または不正 | `settings-gen.ts` |
| 機能コンポーネントが見つからない | 機能モジュールのファイルコピーまたはアンカー不一致 | `features/*.ts`または`templates/features/*/files/` |
| アンカーが出力に残っている | injectionアンカーが未クリーンアップ | `compose.ts` — `cleanAnchors()` |

## 主要なジェネレーターファイル

| ファイル | 役割 |
|----------|------|
| `packages/create-zudo-doc/src/scaffold.ts` | パイプライン統括: ベースコピー、設定生成、機能合成 |
| `packages/create-zudo-doc/src/compose.ts` | 合成エンジン: injection、アンカークリーンアップ、機能解決 |
| `packages/create-zudo-doc/src/features/*.ts` | 各機能のinjection定義モジュール |
| `packages/create-zudo-doc/src/astro-config-gen.ts` | `astro.config.ts`のプログラマティック生成 |
| `packages/create-zudo-doc/src/content-config-gen.ts` | `content.config.ts`のプログラマティック生成 |
| `packages/create-zudo-doc/src/settings-gen.ts` | `settings.ts`の生成 |
| `packages/create-zudo-doc/src/constants.ts` | 機能定義、カラースキームリスト |
| `packages/create-zudo-doc/src/cli.ts` | CLI引数のパース |
| `packages/create-zudo-doc/src/api.ts` | プログラマティックAPI |

## 注意事項

- テストディレクトリは`__inbox/`（gitignored）に作成され、リポジトリを汚染しません
- `barebone`パターンがベースライン — 失敗した場合、他のテストの前に修正してください
- `designTokenPanel` は `--design-token-panel` CLIフラグとしても利用可能ですが、`design-token-panel` や `all-features` などのパターンは他のテストパターンとの一貫性のためプログラマティックAPIで駆動しています
- `--headless`フラグはプロセスレベルのチェックに加えて、ブラウザレベルのレンダリングチェックを追加します
- テスト前と各修正後には必ずCLIを再ビルド（`packages/create-zudo-doc`で`pnpm build`）してください

---

# インストール

> Source: /pj/zudo-doc/ja/docs/getting-started/installation

## 前提条件

- **Node.js 18+** — Astro 6 に必要
- **pnpm** — 推奨パッケージマネージャー

npm、yarn、bun も使用できますが、このガイドでは pnpm を使用します。

## 新規プロジェクトの作成

`create-zudo-doc` CLI を使うと、対話式のセットアップウィザードで新規プロジェクトをすばやく作成できます。

```bash
pnpm create zudo-doc
```

他のパッケージマネージャーの場合:

```bash
npm create zudo-doc
yarn create zudo-doc
bunx create-zudo-doc
```

非対話的な使用（CI、自動化、AI エージェント）では、`--yes` でデフォルトを使用するか、フラグを直接指定できます:

```bash
pnpm create zudo-doc my-docs --yes
pnpm create zudo-doc my-docs --lang ja --scheme Dracula --no-i18n --pm pnpm --install
```

すべてのフラグについては [CLI リファレンス](/ja/docs/reference/create-zudo-doc) を参照してください。

CLI では以下のオプションを順番に設定します。

### プロジェクト名

プロジェクトディレクトリの名前を入力します（デフォルト: `my-docs`）。

### デフォルト言語

ドキュメントサイトのデフォルト言語を選択します。英語、日本語、中国語（簡体字/繁体字）、韓国語、スペイン語、フランス語、ドイツ語、ポルトガル語がサポートされています。

### カラースキームモード

サイトのカラースキーム設定を選択します。

- **Light & Dark（トグル）** — ユーザーがライトとダークテーマを切り替え可能。事前設定されたペアリング（GitHub、Catppuccin、Solarized、Rosé Pine、Atom One、Everforest、Gruvbox、Ayu）から選択するか、ライトとダークのスキームを個別に選べます。
- **Single scheme** — サイト全体で1つの固定カラースキーム。Dracula、Nord、TokyoNight など40のスキームが利用できます。

Light/Dark モードでは、デフォルトモード（ライトまたはダーク）の設定や、ユーザーのシステムカラースキーム設定を尊重するかどうかも選択できます。

### 機能選択

オプション機能を選択します。

| 機能 | デフォルト | 説明 |
|------|-----------|------|
| [i18n（多言語対応）](/ja/docs/guides/i18n/) | オフ | セカンダリ言語をミラーリングしたコンテンツディレクトリで追加 |
| [Pagefind 検索](/ja/docs/guides/search/) | オン | ドキュメント全体の全文検索 |
| [サイドバーフィルター](/ja/docs/guides/sidebar-filter/) | オン | サイドバーナビゲーションのリアルタイムフィルタリング |
| [Claude Resources](/ja/docs/guides/claude-resources/) | オフ | Claude Code コンポーネントの自動生成ドキュメント |
| [カラースキームプレビュー](/ja/docs/guides/color-scheme-preview/) | オフ | カラー調整パネルで50以上のプリセットカラースキームを閲覧 |

### パッケージマネージャー

使用するパッケージマネージャーを選択します: pnpm（推奨）、npm、yarn、bun。スキャフォールディング後に依存関係をインストールするか確認されます。

インストーラーは選択内容に基づいて `src/config/settings.ts` を生成します。プロジェクト作成後にいつでも設定を変更できます。

## 代替方法: リポジトリのクローン

リポジトリを直接クローンして始めることもできます。

```bash
git clone https://github.com/zudolab/zudo-doc.git my-docs
cd my-docs
pnpm install
```

リポジトリのクローンでは、ドキュメントソースとすべての機能が含まれた完全なプロジェクトが取得できます。コードベース全体を確認したい場合や、zudo-doc 自体に貢献したい場合にこの方法を使用してください。

## 開発

```bash
pnpm dev
```

Viteによるインスタントなホットモジュールリプレースメントで開発サーバーがポート4321で起動します。

ポート4321が使用可能であることを確認してください。別のプロセスが使用中の場合、Astro は自動的に次の使用可能なポートを選択します。

## ビルド

```bash
pnpm build
```

`dist/` ディレクトリに静的HTMLが生成されます。任意の静的ホスティングサービスにデプロイできます。

## 型チェック

```bash
pnpm check
```

Astro の組み込み型チェッカーを strict TypeScript モードで実行します。

`dist/` ディレクトリはソース管理にコミットしないでください。`.gitignore` で除外済みです。

## プロジェクト構成

インストール後のプロジェクト構成は以下の通りです:

```
src/
├── components/          # Astro + Preact コンポーネント
│   └── admonitions/     # Note, Tip, Info, Warning, Danger
├── config/
│   ├── settings.ts      # サイト名、アクティブなカラースキーム
│   ├── color-schemes.ts # 利用可能なカラープリセット
│   └── color-scheme-utils.ts
├── content/
│   ├── docs/            # 英語 MDX コンテンツ
│   └── docs-ja/         # 日本語 MDX コンテンツ
├── layouts/             # ページレイアウト
├── pages/               # ファイルベースルーティング
└── styles/
    └── global.css       # デザイントークン & Tailwind 設定
```

ドキュメントページの作成と整理方法については、[ドキュメントの書き方](/ja/docs/getting-started/writing-docs) ガイドを参照してください。

---

# フロントマター

> Source: /pj/zudo-doc/ja/docs/guides/frontmatter

zudo-docのすべてのMDXファイルは`---`で区切られたYAMLフロントマターブロックで始まります。このページでは利用可能なすべてのフィールドを説明します。

## 完全な例

```mdx
---
title: My Documentation Page
description: A comprehensive guide to something important.
sidebar_position: 3
sidebar_label: My Page
tags: [tutorial, setup]
---

Your content here.
```

## 最小限の例

必須なのは`title`のみです：

```mdx
---
title: Quick Start
---
```

## フィールド一覧

| フィールド | 型 | 必須 | デフォルト | 説明 |
|-------|------|----------|---------|-------------|
| `title` | string | はい | -- | ページタイトル。見出し、サイドバー、ブラウザタブに表示 |
| `description` | string | いいえ | -- | タイトル下に表示されるサブタイトル |
| `sidebar_position` | number | いいえ | `999` | サイドバーカテゴリ内のソート順 |
| `sidebar_label` | string | いいえ | `title`の値 | サイドバーに表示されるラベルのオーバーライド |
| `category` | string | いいえ | ディレクトリ名 | 将来の使用のために予約 |
| `search_exclude` | boolean | いいえ | `false` | ページを検索インデックスから除外 |
| `tags` | string[] | いいえ | -- | 横断的なナビゲーション用タグ |
| `draft` | boolean | いいえ | `false` | 本番ビルドから除外（開発時は表示） |
| `unlisted` | boolean | いいえ | `false` | ビルドされるがサイドバー、検索、検索エンジンから非表示 |
| `hide_sidebar` | boolean | いいえ | `false` | 左サイドバーを非表示にし、コンテンツを狭いコンテナに中央揃え |
| `hide_toc` | boolean | いいえ | `false` | 右側の目次を非表示 |
| `doc_history` | boolean | いいえ | 自動 | doc-historyボタンの表示を上書き（自動：`*/index`ページは非表示、詳細ページは表示） |
| `standalone` | boolean | いいえ | `false` | サイドバーナビゲーションから非表示だがインデックスされる（`unlisted`とは異なる） |
| `slug` | string | いいえ | ファイルパスから導出 | カスタムURLスラグのオーバーライド |
| `pagination_next` | string \| null | いいえ | 自動 | 次のページリンクをオーバーライド、`null`で非表示 |
| `pagination_prev` | string \| null | いいえ | 自動 | 前のページリンクをオーバーライド、`null`で非表示 |

## フィールド詳細

### `title`

- **型：** `string`
- **必須：** はい

ページタイトル。ページの`h1`見出し、サイドバーナビゲーション、ブラウザタブ、検索結果に表示されます。

```mdx
---
title: Getting Started with zudo-doc
---
```

### `description`

- **型：** `string`
- **必須：** いいえ

ページの短い説明またはサブタイトル。レンダリングされたページでタイトルの下に表示されます。SEOメタタグにも使用されます。

```mdx
---
title: Installation
description: How to install and set up zudo-doc for your project.
---
```

### `sidebar_position`

- **型：** `number`
- **必須：** いいえ
- **デフォルト：** `999`（末尾に表示）

サイドバーカテゴリ内のページのソート順を制御します。小さい数値ほど先に表示されます。

```mdx
---
title: Introduction
sidebar_position: 1
---
```

カテゴリインデックスページ（`index.mdx`）では、`sidebar_position`はカテゴリ全体がサイドバー内の他のカテゴリに対してどこに表示されるかも制御します。

### `sidebar_label`

- **型：** `string`
- **必須：** いいえ
- **デフォルト：** `title`の値

サイドバーナビゲーションに表示されるラベルをオーバーライドします。完全なページタイトルよりも短い、または異なるラベルを表示したい場合に使用します。

```mdx
---
title: Configuring Color Schemes and Themes
sidebar_label: Color Schemes
---
```

### `category`

- **型：** `string`
- **必須：** いいえ
- **デフォルト：** ディレクトリ構造から導出（最初のディレクトリセグメント）

将来の使用のために予約されています。このフィールドはコンテンツスキーマで定義されていますが、現在はサイドバーやルーティングロジックでは使用されていません。カテゴリは常にディレクトリ構造から導出されます。

ページをカテゴリに整理するには、`src/content/docs/`の下にディレクトリを作成してその中に配置します。ディレクトリ名がカテゴリ名になります。

### `search_exclude`

- **型：** `boolean`
- **必須：** いいえ
- **デフォルト：** `false`

`true`に設定すると、ページを検索インデックスから除外します。検索結果に表示すべきでない内部ページ、変更履歴、インポートされたコンテンツに便利です。

```mdx
---
title: Internal Changelog
search_exclude: true
---
```

### `tags`

- **型：** `string[]`
- **必須：** いいえ

横断的なナビゲーション用のタグをページに割り当てます。タグはページにクリック可能なバッジとして表示され、タグインデックスページが`/docs/tags/`と`/docs/tags/[tag]`に自動生成されます。

詳しい使い方は[タグガイド](./tags.mdx)を参照してください。

タグ付きページは3か所に表示されます：

1. **各ドキュメントの下部** — タグ付きページの前/次ページャーの直上に、タグバッジの行が表示されます。
2. **ホームページ** — ドキュメントで使用されているすべてのタグを一覧表示する「All tags」セクションがあり、各タグのインデックスページへリンクします。
3. **タグインデックス** — [/docs/tags/](/docs/tags/) の共有インデックスで、タグごとにすべてのページをグループ化して表示します。

```mdx
---
title: Deploying to Netlify
tags: [deployment, netlify, hosting]
---
```

タグは、異なるサイドバーカテゴリにまたがる関連ページをグループ化するのに便利です。

### `draft`

- **型：** `boolean`
- **必須：** いいえ
- **デフォルト：** `false`

`true`に設定すると、ページは本番ビルドから完全に除外されます。下書きページはプレビュー目的で開発時（`pnpm dev`）には引き続き表示されます。

```mdx
---
title: Upcoming Feature
draft: true
---
```

### `unlisted`

- **型：** `boolean`
- **必須：** いいえ
- **デフォルト：** `false`

`true`に設定すると、ページはビルドされてURL経由でアクセス可能ですが、サイドバーナビゲーション、検索インデックス、検索エンジン（`noindex`メタタグ経由）からは非表示になります。

```mdx
---
title: Internal Notes
unlisted: true
---
```

### `hide_sidebar`

- **型：** `boolean`
- **必須：** いいえ
- **デフォルト：** `false`

`true`に設定すると、デスクトップで左側のサイドバーが非表示になり、コンテンツが狭いコンテナに中央揃えで表示されます。モバイルのハンバーガーメニューからは引き続きナビゲーションにアクセスできます。ランディングページ、スタンドアロンの記事、フルワイドの読書体験が望ましいページに便利です。

```mdx
---
title: About This Project
hide_sidebar: true
---
```

[ライブデモ](/ja/docs/guides/layout-demos/hide-sidebar/)でこのレイアウトオプションを実際に確認できます。

### `hide_toc`

- **型：** `boolean`
- **必須：** いいえ
- **デフォルト：** `false`

`true`に設定すると、右側の目次（セクションナビゲーション）とモバイルの目次の両方が非表示になります。メインコンテンツエリアが利用可能な幅いっぱいに広がります。

```mdx
---
title: Changelog
hide_toc: true
---
```

[ライブデモ](/ja/docs/guides/layout-demos/hide-toc/)でこのレイアウトオプションを実際に確認できます。

`hide_sidebar`と`hide_toc`を組み合わせて、ナビゲーションパネルのないクリーンでセンタリングされた読みやすいレイアウトを作成できます：

```mdx
---
title: About
hide_sidebar: true
hide_toc: true
---
```

両方のオプションを組み合わせた[ライブデモ](/ja/docs/guides/layout-demos/hide-both/)もご覧ください。

### `standalone`

- **型：** `boolean`
- **必須：** いいえ
- **デフォルト：** `false`

`true`に設定すると、ページはサイドバーナビゲーションとサイトインデックスから非表示になりますが、URL経由でアクセス可能で検索エンジンにインデックスされます。`unlisted`とは異なり、standaloneページには`noindex`メタタグが付きません。

```mdx
---
title: Terms of Service
standalone: true
---
```

公開アクセス可能であるべきだがドキュメントナビゲーションには含めたくないページ（利用規約、特別なランディングページなど）には`standalone`を使用します。検索エンジンのインデックスも防ぎたい場合は`unlisted`を使用します。

### `slug`

- **型：** `string`
- **必須：** いいえ
- **デフォルト：** ファイルパスから導出

ページのURLスラグをオーバーライドします。ファイルパスから生成されるURLとは異なるURLにしたい場合に使用します。

```mdx
---
title: Getting Started with zudo-doc
slug: quickstart
---
```

このページはファイルの場所から導出されるデフォルトパスの代わりに`/docs/quickstart`でアクセスできるようになります。

### `pagination_next`

- **型：** `string | null`
- **必須：** いいえ
- **デフォルト：** サイドバーの順序から自動的に決定

ドキュメントの下部に表示される「次へ」ページリンクをオーバーライドします。ドキュメントパス（例：`"guides/configuration"`）を設定して特定のページにリンクするか、`null`に設定して次のリンクを完全に非表示にします。

```mdx
---
title: Final Step
pagination_next: null
---
```

### `pagination_prev`

- **型：** `string | null`
- **必須：** いいえ
- **デフォルト：** サイドバーの順序から自動的に決定

ドキュメントの下部に表示される「前へ」ページリンクをオーバーライドします。ドキュメントパス（例：`"getting-started/introduction"`）を設定して特定のページにリンクするか、`null`に設定して前のリンクを完全に非表示にします。

```mdx
---
title: Getting Started
pagination_prev: null
---
```

---

# デモ: 目次非表示

> Source: /pj/zudo-doc/ja/docs/guides/layout-demos/hide-toc

このページは`hide_toc: true`フロントマターオプションのデモです。右側の目次が非表示になり、メインコンテンツエリアが利用可能な幅いっぱいに広がります。

## 何が起きているか

このページでは目次が非表示になっています。使用しているフロントマターは以下の通りです：

```yaml
---
title: "デモ: 目次非表示"
hide_sidebar: false
hide_toc: true
---
```

## サイドバーは表示されたまま

左側のサイドバーは引き続きナビゲーション用に表示されます。右側の目次のみが影響を受けます。

## デスクトップとモバイル

`hide_toc: true`を設定すると、デスクトップの目次（右サイドバー）とモバイルの目次の両方が非表示になります。

### サブセクションの例

このサブセクションは、ページに見出しやサブセクションがあっても目次が生成されないことを示すために存在しています。

## 使用場面

見出しが少ないページ、短いコンテンツ、またはセクションナビゲーションよりもコンテンツの幅が重要な場合に`hide_toc: true`を使用します。

詳しくは[フロントマターリファレンス](/ja/docs/guides/frontmatter/#hide_toc)をご覧ください。

## 関連ページ

- [サイドバー非表示](/ja/docs/guides/layout-demos/hide-sidebar/) — 左側のサイドバーを非表示にします
- [サイドバー＆目次非表示](/ja/docs/guides/layout-demos/hide-both/) — 両方のパネルを非表示にします

---

# コンポーネントファースト戦略

> Source: /pj/zudo-doc/ja/docs/reference/component-first

zudo-docは**コンポーネントファースト戦略**に従います：UIは常にTailwindユーティリティクラスを持つコンポーネントとして表現します。カスタムCSSクラス名を別のスタイルシートで作成することはしません。

## 問題

ユーティリティCSSフレームワークとコンポーネントフレームワークを併用するプロジェクトでは、開発者は従来のCSSパターンに戻りがちです。コンポーネント内でユーティリティクラスを組み合わせる代わりに、`.profile-card`、`.btn-primary`、`.sidebar-nav`といったカスタムCSSクラス名を別のスタイルシートやCSSモジュールで作成します。

これにより、コードベースが断片化します：

- ユーティリティをインラインで使うコンポーネント
- カスタムCSSクラスを導入するコンポーネント
- 両方のアプローチを混在させるコンポーネント

## ルール

**コンポーネント自体が抽象化です。** `.card`や`.btn-primary`のようなCSSクラス名は不要です。コンポーネントがカプセル化を、ユーティリティクラスがスタイリングを担当します。

- カードが必要？ → ユーティリティクラスを持つ``コンポーネントを作成
- ボタンバリアント？ → ``コンポーネント
- レイアウトパターン？ → ``コンポーネント

## zudo-docでの実践

zudo-docは**Astroコンポーネント**（`.astro`）と**Preactアイランド**（`.tsx`）を**Tailwind CSS v4**ユーティリティとともに使用します。

### Astroコンポーネント

```astro
<!-- ユーティリティクラスをインラインで使用 -->

  
    
  

```

`.footer`クラスなし。`footer.module.css`なし。コンポーネント**が**抽象化です。

### アンチパターン

```css
/* 間違い — カスタムCSSクラスを作成しない */
.profile-card { display: flex; gap: 1rem; }
```

```astro
<!-- 間違い — カスタムクラス名はデザインシステムをバイパスする -->
...

<!-- 正しい — ユーティリティクラス、コンポーネントが抽象化 -->
...
```

## バリアントはPropsで

CSSモディファイアクラス（`.btn--primary`）ではなく、コンポーネントプロップスを使用：

```tsx
function Button({ variant = "primary", children }) {
  const styles = {
    primary: "bg-accent text-bg hover:bg-accent-hover",
    secondary: "bg-surface text-fg border border-muted",
  };
  return (
    
      {children}
    
  );
}
```

## デザイントークンを使用

任意の値ではなく、プロジェクトトークンを常に使用：

```astro
<!-- 間違い — 任意の値はデザインシステムをバイパスする -->

<!-- 正しい — デザイントークンを使用 -->

```

利用可能なトークンについては[デザインシステム](/ja/docs/reference/design-system)を参照してください。

## カスタムCSSが許容される場合

zudo-docでカスタムCSSが許容される唯一の場所は`src/styles/global.css`です：

- **コンテンツタイポグラフィ** — `.zd-content`クラスはMDXパイプラインが生成する要素をスタイリング
- **デザイントークン定義** — Tailwindトークンを登録する`@theme`ブロック

それ以外のすべて（すべてのコンポーネント、レイアウト、UI要素）はユーティリティクラスを直接使用します。

## ルールのまとめ

1. **常にコンポーネントを作成** — CSSクラスではなく
2. **ユーティリティクラスを直接使用** — コンポーネントマークアップ内で
3. **CSSモジュールファイルやカスタムクラス名を作成しない**
4. **バリアントにはプロップスを使用** — CSSモディファイアではなく
5. **コンポーネントを組み合わせる** — より多くのCSSではなく、小さなコンポーネントから複雑なUIを構築
6. **プロジェクトトークンを使用** — `text-fg`、`bg-surface`、`p-hsp-md`、任意の値ではなく

---

# セットアッププリセットジェネレーター

> Source: /pj/zudo-doc/ja/docs/getting-started/setup-preset-generator

このインタラクティブツールを使って、zudo-docプロジェクトのオプションを設定し、セットアッププリセットを生成できます。出力はプログラマティックAPI用のJSON、またはターミナル用のCLIコマンドとしてコピーできます。

## ヘッダー右側アイテム

「Header right items」セクションは `settings.headerRightItems` — サイトヘッダー右側のクラスタ(テーマ切替、言語スイッチャー、バージョンスイッチャー、GitHub リンク、Design Token Panel / AI Chat トリガー)を構成します。各アイテムのオン・オフを切り替え、上下ボタンで描画順を変更できます。

2 種類のアイテム — `link`(任意の外部リンク)と `html`(生 HTML)— は、意図的に UI に出していません。これらを使う場合はスキャフォールド後に `settings.ts` を直接編集してください。discriminated union のスキーマと使用例は [ヘッダー右側アイテム](../guides/header-right-items.mdx) を参照してください。

## 新しく追加された機能

Features セクションには、いくつか押さえておきたい新項目があります。

- **Image enlarge** — コンテンツ画像のクリック拡大。デフォルトで有効。
- **Tag governance** — タグの語彙ルール監査。デフォルトで有効。詳細は [タグガバナンス](../guides/tag-governance.mdx)。
- **Body foot util area** — 記事本文の末尾にタグリストやフィードバックリンクなどのユーティリティを差し込めるスロット。詳細は [Body foot util area](../guides/body-foot-util-area.mdx)。
- **Footer taglist** — サイトフッターにグローバルタグクラウドを表示します。詳細は [Footer taglist](../guides/footer-taglist.mdx)。
- **Design Token Panel** — 旧称「Color tweak panel」を改称。設定キーは `designTokenPanel`。互換のため `colorTweakPanel` も引き続きエイリアスとして使えます。

---

# タブ

> Source: /pj/zudo-doc/ja/docs/components/tabs

`` と `` を使用して、タブ付きコンテンツパネルを作成できます。どちらのコンポーネントもグローバルに利用可能で、インポートは不要です。

## 基本的な使い方

  
    ```bash
    npm install zudo-doc
    ```
  
  
    ```bash
    pnpm add zudo-doc
    ```
  
  
    ```bash
    yarn add zudo-doc
    ```
  

````mdx

  
    ```bash

    npm install zudo-doc

    ```
  
  
    ```bash

    pnpm add zudo-doc

    ```
  
  
    ```bash

    yarn add zudo-doc

    ```
  

````

`TabItem` の `default` プロップは、最初にアクティブになるタブを設定します。省略した場合、最初のタブが表示されます。

## 同期タブ

`groupId` を使用すると、同じページ内の複数のタブグループでタブの選択を同期できます。選択されたタブは localStorage に保持されるため、ページ遷移後も維持されます。

  
    ```js
    console.log("Hello");
    ```
  
  
    ```ts
    console.log("Hello" as string);
    ```
  

  
    ```js
    const sum = (a, b) => a + b;
    ```
  
  
    ```ts
    const sum = (a: number, b: number): number => a + b;
    ```
  

````mdx

  
    ```js

    console.log("Hello");

    ```
  
  
    ```ts

    console.log("Hello" as string);

    ```
  

<!-- 上のグループでタブを選択すると、このグループも同期されます -->

  
    ```js

    const sum = (a, b) => a + b;

    ```
  
  
    ```ts

    const sum = (a: number, b: number): number => a + b;

    ```
  

````

## Tabs プロップ

| プロップ | 型 | デフォルト | 説明 |
|------|------|---------|-------------|
| `groupId` | string | — | 同じ `groupId` を持つグループ間でタブの選択を同期します（localStorage に保持） |

## TabItem プロップ

| プロップ | 型 | デフォルト | 説明 |
|------|------|---------|-------------|
| `label` | string | （必須） | タブボタンのテキスト |
| `value` | string | `label` の値 | タブの一意な識別子 |
| `default` | boolean | `false` | 最初にアクティブになるタブとして設定 |

---

# リンクチェッカー

> Source: /pj/zudo-doc/ja/docs/develop/link-checker

# リンクチェッカー

zudo-docには、サイトビルド後に2種類の検証を行う組み込みリンクチェッカー（`scripts/check-links.js`）が含まれています。

## チェック内容

### モード1: ビルド済みHTMLスキャン

`dist/`内のすべての`.html`ファイルをスキャンし、内部``リンクの各ターゲットがディスク上に存在するかを検証します。以下を処理します：

- ベースパスの除去（例：`/pj/zudo-doc/docs/foo` → `docs/foo`）
- 末尾スラッシュの解決（`docs/foo/` → `docs/foo/index.html`）
- 拡張子の解決（`docs/foo` → `docs/foo/index.html`または`docs/foo.html`）
- 解決前のクエリ文字列とフラグメントの除去
- ファイルのディレクトリに対する相対リンクの解決
- パフォーマンスのための解決済みパスのキャッシュ

スキップされるリンク（チェック対象外）：

- 外部URL（`https://`、`http://`）
- アンカーのみのリンク（`#section`）
- `mailto:`、`javascript:`、`data:`、`tel:` URI
- バージョン付きドキュメントリンク（`/v/*/`） — バージョンコンテンツが不完全な場合があるため

### モード2: MDXソーススキャン

設定されたコンテンツディレクトリ内のすべての`.mdx`および`.md`ファイルをスキャンし、ベースパスをバイパスする絶対リンクを検出します。以下のようなリンクが対象です：

```mdx
<!-- これらはフラグされます — ベースパスをバイパスしています -->
[guide](/docs/guides/foo)
link

<!-- これらは問題ありません — 相対パスを使用しています -->
[guide](./foo.mdx)
[guide](../other/bar.mdx)
```

ベースパスが設定されている場合（例：`/pj/zudo-doc/`）、`/docs/`や`/ja/docs/`で始まる絶対リンクはベースパスのプレフィックスが欠けているため壊れます。MDXソーススキャンは、これらが本番環境で壊れたリンクになる前に検出します。

フェンスドコードブロック内のリンクは無視されます。

## リンクチェッカーの実行

### 単独実行

まずサイトをビルドし、チェッカーを実行します：

```bash
pnpm build && pnpm check:links
```

### `--strict`フラグ

デフォルトでは、問題が見つかってもチェッカーは終了コード0で終了します（非strictモード）。問題発見時に失敗させるには`--strict`を使用します：

```bash
pnpm check:links --strict
```

### b4pushの一部として

リンクチェッカーはプッシュ前検証（`pnpm b4push`）の5ステップ中ステップ4で実行されます：

1. フォーマットチェック
2. 型チェック
3. ビルド
4. **リンクチェック**
5. E2Eテスト

### CI内での実行

リンクチェッカーはPRチェックワークフロー（`pr-checks.yml`）の`build-site`ジョブで、`pnpm build`の直後に実行されます。

## 出力

問題がない場合：

```
Checking links (base: /pj/zudo-doc/)...

✓ No broken links or absolute path issues found
```

問題がある場合：

```
Checking links (base: /pj/zudo-doc/)...

=== Broken Links in Built HTML ===
  dist/docs/page/index.html:42  /pj/zudo-doc/docs/missing-page

=== Absolute Links Bypassing Base Path (MDX Source) ===
  src/content/docs/guides/test.mdx:15  /docs/guides/foo

✗ Found 1 broken link and 1 absolute path warning
```

各エントリはファイルパス、行番号、問題のあるhrefを表示します。

## 設定

リンクチェッカーは`src/config/settings.ts`から設定を読み取ります：

- **`base`** — サイトのベースパス。リンク解決時のプレフィックス除去に使用
- **`docsDir`** — MDXソーススキャンのプライマリコンテンツディレクトリ
- **`locales`** — ロケール設定。`dir`フィールドでMDXソーススキャンの追加コンテンツディレクトリを指定（例：`locales: { ja: { dir: "src/content/docs-ja" } }`）

---

# ドキュメントの書き方

> Source: /pj/zudo-doc/ja/docs/getting-started/writing-docs

## ドキュメントの作成

`src/content/docs/` に `.mdx` ファイルを作成します。フロントマターでメタデータを指定してください：

```mdx
---
title: マイページ
description: このページの簡単な説明。
sidebar_position: 1
---

ここにコンテンツを記述します。
```

### フロントマターフィールド

| フィールド | 型 | 必須 | 説明 |
|-------|------|----------|-------------|
| `title` | string | はい | ページタイトル（サイドバーとヘッダーに表示） |
| `description` | string | いいえ | タイトルの下に表示される説明文 |
| `sidebar_position` | number | いいえ | カテゴリ内の並び順（小さい値が先） |
| `sidebar_label` | string | いいえ | サイドバーの表示名を上書き |

ドキュメントのコンテンツ内で `# h1` 見出しを使用しないでください。フロントマターの `title` がページタイトル（h1）として自動的にレンダリングされます。コンテンツは `## h2` 見出しから始めてください。

利用可能なすべてのフィールドの完全なリファレンスは[フロントマターガイド](../guides/frontmatter.mdx)をご覧ください。

## ディレクトリ構造

ディレクトリを使ってドキュメントをカテゴリに整理します：

```
src/content/docs/
  getting-started/
    introduction.mdx      # sidebar_position: 1
    installation.mdx       # sidebar_position: 2
    writing-docs.mdx       # sidebar_position: 3
  guides/
    configuration.mdx      # sidebar_position: 1
    sidebar.mdx            # sidebar_position: 2
```

各ディレクトリは自動的にサイドバーの折りたたみ可能なカテゴリになります。カテゴリ名はディレクトリ名から自動生成されます（ケバブケースからタイトルケースに変換）。

## ドキュメント間のリンク

**相対ファイルパス**を使って他のドキュメントにリンクできます：

```mdx
[インストールガイド](./installation.mdx)
[フロントマターリファレンス](../guides/frontmatter.mdx)
[インデックスに戻る](./index.mdx)
```

これらの相対パスはビルド時に正しいURLに自動的に解決されます。リンクリゾルバーが動作するには `.md`/`.mdx` 拡張子が必要です。これによりファイルリンクとURLリンクを区別します。

アンカーやクエリ文字列も含めることができます：

```mdx
[フロントマターフィールド](../guides/frontmatter.mdx#required-fields)
```

相対リンクはビルド時に検証されます。リンク先のファイルが存在しない場合、ビルド出力に警告が表示されます。これにより壊れたリンクを早期に検出できます。

外部リンクやドキュメント以外のページへのリンクには、通常のURLを使用してください：

```mdx
[Astroドキュメント](https://docs.astro.build)
[APIリファレンス](/api/v1)
```

## アドモニション

zudo-docはDocusaurusスタイルのアドモニションをサポートしています。グローバルに登録されているため、インポート不要です：

これは**ノート**です — 読者が知っておくべき一般的な情報に使用します。

これは**ヒント**です — 役立つ提案やベストプラクティスに使用します。

これは**情報**ブロックです — 追加のコンテキストや背景情報に使用します。

これは**警告**です — 潜在的な問題や注意点をフラグするために使用します。

これは**危険**アラートです — データ損失や破壊的変更に関する重大な警告に使用します。

### カスタムタイトル

`title` プロップを使って、任意のアドモニションにカスタムタイトルを設定できます。

### アドモニションの構文

2つの構文がサポートされています。どちらもインポート不要です。

**ディレクティブ構文**（コンテンツ作成者向け推奨）：

```mdx
:::note[任意のタイトル]

ここにコンテンツを記述します。

:::
```

**JSXコンポーネント構文**：

```mdx

自動生成タイトルのデフォルトノート。

カスタムタイトルの警告。

```

各アドモニションタイプは、ボーダーとタイトルの色にパレットスロットがマッピングされています：

| タイプ | パレットスロット | 一般的な色 |
|------|-------------|---------------|
| Note | p4 | 青 |
| Tip | p2 | 緑 |
| Info | p6 | シアン |
| Warning | p3 | 黄 |
| Danger | p1 | 赤 |

アドモニションやコードブロックなど、利用可能なすべてのコンポーネントの一覧は[コンポーネント](/ja/docs/components/)リファレンスをご覧ください。

## i18n（国際化）

zudo-docは英語と日本語をすぐに使える状態でサポートしています。日本語ドキュメントは `src/content/docs-ja/` で英語のディレクトリ構造をミラーリングします。

翻訳と言語ルーティングの管理に関する詳しい手順は[i18nガイド](/ja/docs/guides/i18n)をご覧ください。

## MDXの機能

ドキュメント内でPreactコンポーネントを使用できます。インタラクティブなコンポーネントはAstroアイランドとしてハイドレートされ、残りは純粋なHTMLとしてJavaScriptゼロで配信されます。

```mdx

```

インタラクティブ性が必要なコンポーネントには `client:load` を使用してください。静的HTMLのみをレンダリングするコンポーネントでは省略します。

## ナビゲーション

zudo-docは以下を自動生成します：

- **サイドバー** — `sidebar_position` でソートされたアイテムを持つ折りたたみ可能なカテゴリ
- **目次** — 右サイドバーにh2〜h4の見出し（ワイドスクリーンで表示）
- **前/次リンク** — ドキュメント間のボトムナビゲーション
- **パンくずリスト** — タイトルの上に表示されるカテゴリパス

---

# デモ: サイドバー＆目次非表示

> Source: /pj/zudo-doc/ja/docs/guides/layout-demos/hide-both

このページは`hide_sidebar: true`と`hide_toc: true`を組み合わせたデモです。両方のナビゲーションパネルが非表示になり、クリーンでセンタリングされた読みやすいレイアウトになります。

## 何が起きているか

サイドバーと目次の両方が非表示になっています。使用しているフロントマターは以下の通りです：

```yaml
---
title: "デモ: サイドバー＆目次非表示"
hide_sidebar: true
hide_toc: true
---
```

## クリーンな読書体験

両方のパネルを削除すると、コンテンツはページの中央に狭いコンテナで配置されます。このレイアウトは以下のような用途に最適です：

- ランディングページ
- スタンドアロンの記事
- 集中して読むコンテンツ
- アバウトページ

## モバイルナビゲーション

両方のパネルが非表示になっていても、モバイルのハンバーガーメニューから引き続きナビゲーションにアクセスできます。読者がナビゲーション手段を失うことはありません。

### サブセクションの例

このサブセクションは、見出しが通常通りレンダリングされることを示しています。目次に表示されないだけです。

## 使用場面

コンテンツ自体に最大限集中したい場合に、両方のオプションを組み合わせて使用します。

詳しくは[フロントマターリファレンス](/ja/docs/guides/frontmatter/#hide_sidebar)をご覧ください。

## 関連ページ

- [サイドバー非表示](/ja/docs/guides/layout-demos/hide-sidebar/) — 左側のサイドバーのみを非表示にします
- [目次非表示](/ja/docs/guides/layout-demos/hide-toc/) — 右側の目次のみを非表示にします

---

# サイドバー

> Source: /pj/zudo-doc/ja/docs/guides/sidebar

## アイテムの並び順

カテゴリ内のページは`sidebar_position`フロントマターフィールドでソートされます。小さい値ほど先に表示されます。

`sidebar_position`がないページはデフォルト値`999`が適用され、カテゴリの末尾にファイル名のアルファベット順で表示されます。

```mdx
---
title: My Page
sidebar_position: 3
---
```

ページの順序を制御するために、`sidebar_position`を常に明示的に設定してください。設定しないとページはアルファベット順にソートされ、意図した読み順と一致しない場合があります。

## カテゴリの並び順

サイドバー内のカテゴリは**インデックスページ**（`index.mdx`）の`sidebar_position`で順序付けされます。カテゴリにインデックスページがない場合や`sidebar_position`がない場合は、アルファベット順にフォールバックします。

例えば、「Getting Started」を最初に、「Guides」を2番目にするには：

```
getting-started/index.mdx  → sidebar_position: 0
guides/index.mdx            → sidebar_position: 1
reference/index.mdx         → sidebar_position: 2
```

## カテゴリインデックスページ

ディレクトリ内に`index.mdx`を作成すると、カテゴリにランディングページが付与されます。サイドバーのカテゴリ名がこのページへのクリック可能なリンクになります。

一般的なカテゴリインデックスページでは``コンポーネントを使用して、カテゴリ内のすべてのページを自動的にリスト表示します：

```mdx
---
title: Guides
sidebar_position: 1
---

Explore our guides to learn about zudo-doc features.

```

``コンポーネントは、カテゴリ内のすべてのページ（インデックス自体を除く）へのリンクのグリッドを`sidebar_position`でソートしてレンダリングします。

`index.mdx`がない場合、カテゴリの見出しはトグル専用のコントロールになります — クリックするとカテゴリの展開・折りたたみが行われますが、ページへのナビゲーションは行われません。

## デフォルトの展開・折りたたみ

現在のページが含まれるカテゴリは自動的に展開されます。それ以外のカテゴリはデフォルトで折りたたまれます。

## サイドバーラベル

`sidebar_label`フロントマターフィールドを使用して、ページタイトルとは異なるラベルをサイドバーに表示できます。完全なタイトルがサイドバーには長すぎる場合に便利です。

```mdx
---
title: Getting Started with zudo-doc Installation
sidebar_label: Installation
sidebar_position: 2
---
```

`sidebar_label`はサイドバーにのみ影響します。ページタイトルと見出しには引き続き`title`が使用されます。

## ディレクトリ構造

`src/content/docs/`内のディレクトリがサイドバーカテゴリになります。ディレクトリ名はkebab-caseからTitle Caseに自動的に変換されます。

```
src/content/docs/
  getting-started/         → "Getting Started"
    index.mdx              → カテゴリインデックス (sidebar_position: 0)
    introduction.mdx       → sidebar_position: 1
    installation.mdx       → sidebar_position: 2
    writing-docs.mdx       → sidebar_position: 3
  guides/                  → "Guides"
    index.mdx              → カテゴリインデックス (sidebar_position: 1)
    configuration.mdx      → sidebar_position: 1
    frontmatter.mdx        → sidebar_position: 2
```

## ネストカテゴリ（サブグループ）

カテゴリディレクトリ内にサブディレクトリを作成すると、サイドバーにネストされた折りたたみグループが生成されます。各サブディレクトリには `_category_.json` ファイルが必要です：

```
src/content/docs/
  methodology/
    index.mdx
    architecture/
      _category_.json       → { "label": "Architecture", "position": 1, "noPage": true }
      bem-strategy.mdx
      component-first.mdx
    design-systems/
      _category_.json       → { "label": "Design Systems", "position": 2, "noPage": true }
      tight-token.mdx
      two-tier-size.mdx
```

自動生成サイドバーでは **3レベルの深さ** で表示されます：

```
Methodology            (depth 0)
  ▸ Architecture       (depth 1, 折りたたみ可能)
    BEM Strategy       (depth 2)
    Component First    (depth 2)
  ▸ Design Systems     (depth 1, 折りたたみ可能)
    Tight Token        (depth 2)
    Two-Tier Size      (depth 2)
```

### 明示的サイドバー設定によるフラット化

より読みやすくするため、`src/config/sidebars.ts` で明示的なサイドバー設定を使用してサブグループをトップレベルに昇格できます。ネストが1レベル減少します：

```ts title="src/config/sidebars.ts"
const sidebars: SidebarsConfig = {
  methodology: [
    "methodology",
    {
      type: "category",
      label: "Architecture",
      items: [{ type: "autogenerated", dirName: "methodology/architecture" }],
    },
    {
      type: "category",
      label: "Design Systems",
      items: [{ type: "autogenerated", dirName: "methodology/design-systems" }],
    },
  ],
};
```

**2レベル** で表示されます：

```
Methodology            (depth 0, リーフリンク)
▸ Architecture         (depth 0, 折りたたみ可能)
  BEM Strategy         (depth 1)
  Component First      (depth 1)
▸ Design Systems       (depth 0, 折りたたみ可能)
  Tight Token          (depth 1)
  Two-Tier Size        (depth 1)
```

ポイント：

- 文字列 `"methodology"` はカテゴリインデックスページを **リーフリンク** として参照します（子要素は自動的に除去され、明示的な設定が構造を制御します）
- `type: "autogenerated"` と `dirName` で特定のサブディレクトリから記事を取得します
- サブグループカテゴリは depth 0 で太字ラベルとボーダー区切り付きで表示されます
- 記事は depth 1 で表示され、自動生成より1レベルフラットになります

カテゴリにサブグループがある場合はこのパターンを推奨します。明示的な設定によりファイルシステムの整理を維持しつつ、サイドバーの可読性が向上します。

## ソート順（昇順・降順）

デフォルトでは、カテゴリ内のアイテムは昇順（`sidebar_position`が小さい順、次にアルファベット順）でソートされます。`_category_.json`を使用してカテゴリごとに降順に変更できます：

```json title="_category_.json"
{
  "label": "Changelog",
  "position": 10,
  "sortOrder": "desc"
}
```

`sortOrder`が`"desc"`の場合、アイテムは逆順でソートされます — positionが大きい順、次に逆アルファベット順。これは日付ベースのコンテンツ（変更履歴、リリースノート）で、最新のアイテムを上部に表示したい場合に便利です。

`src/config/sidebars.ts`でも手動サイドバー設定で`sortOrder`を設定できます：

```ts
{
  type: "category",
  label: "Releases",
  sortOrder: "desc",
  items: [
    { type: "autogenerated" },
  ],
}
```

変更履歴スタイルのカテゴリでは、`sortOrder: "desc"`と日付プレフィックスのファイル名（例：`2026-03-10-release.mdx`）を組み合わせることで、`sidebar_position`を手動設定しなくても自動的に最新順に並べられます。

## 並び順の推奨事項

- 予測可能な順序のためにすべてのページに`sidebar_position`を設定する
- カテゴリインデックスページには`sidebar_position: 0`を使用する
- 各カテゴリ内のページには連番（1, 2, 3...）を使用する
- 後でページを挿入する予定がある場合は番号に間隔を空ける（例：10, 20, 30）
- 最新順のカテゴリには`_category_.json`で`sortOrder: "desc"`を使用する

---

# カラー

> Source: /pj/zudo-doc/ja/docs/reference/color

zudo-docは**3層カラー戦略**を採用し、サイト上のすべての色をテーマ切り替え可能にしています。デフォルトのTailwindテーマはインポートされず、`@theme`ブロックで`--color-*: initial`としてカラー名前空間をリセットしてからプロジェクトトークンを定義します。これにより、カラースキームを切り替えるだけでサイト全体が一括で更新されます。

## 3層カラー戦略

カラーは3つの層で構成されています。各層は上位の層のみを参照します：

| 層 | 名前 | 目的 | 定義場所 |
|----|------|------|----------|
| 1 | **パレット** | カラースキームから取得した生のカラー値 | `ColorSchemeProvider` → `:root` |
| 2 | **セマンティック** | デザイン上の意味 — 各色がUIで何を表すか | `src/styles/global.css` `@theme` |
| 3 | **コンポーネント** | 特定コンポーネント向けのスコープ付きオーバーライド | `.zd-content`（`global.css`内） |

この階層構造により：

- **パレットの差し替え**（カラースキーム変更）→ サイト全体が更新
- **セマンティックトークンの再マッピング**（例：`accent`をシアンから青に変更）→ `accent`を使用するすべてのコンポーネントが更新
- **コンポーネントトークンのオーバーライド** → 他のコンポーネントに影響なし

## Tier 1：16色パレット

zudo-docのカラーシステムは**16色パレット**を採用しています。各カラースキームは16のインデックスカラースロットに加え、背景、前景、選択色の値を提供します。

### パレットインデックス規約

すべてのカラースキームはこの標準的なインデックスマッピングに従う必要があります。これにより、コンポーネントとセマンティックトークンがすべてのテーマで一貫して動作します：

| インデックス | 役割 | 説明 |
|-------------|------|------|
| p0 | ダークサーフェス | 最も深いサーフェス（コードブロック、オーバーレイ） |
| p1 | 危険 | 赤系 — エラー、破壊的アクション |
| p2 | 成功 | 緑系 — 確認、ヒント |
| p3 | 警告 | 黄/琥珀系 — 注意メッセージ |
| p4 | 情報 | 青系 — 情報ハイライト |
| p5 | アクセント | 主要なインタラクティブカラー（リンク、CTA） |
| p6 | ニュートラル | スレート/シアン — ボーダー、セカンダリ要素 |
| p7 | セカンダリ | ミュートアクセントまたはセカンダリニュートラル |
| p8 | ミュート | グレー — ボーダー、セカンダリテキスト、コメント |
| p9 | 背景 | ページ背景 |
| p10 | サーフェス | 浮上サーフェス（パネル、サイドバー） |
| p11 | テキストプライマリ | 本文テキスト |
| p12 | アクセントバリアント | より明るい、または代替のアクセント |
| p13 | デコラティブ | 紫/ラベンダー — 非セマンティックな装飾 |
| p14 | アクセントホバー | インタラクティブ要素のホバー状態 |
| p15 | テキストセカンダリ | セカンダリテキストまたはミュートフォアグラウンド |

実際の16進数値はライトスキームとダークスキームで異なりますが、各インデックスの**役割**は同じです。たとえば、p1は常に危険/赤系のカラーで、ライトモードでは`#dd3131`、ダークモードでは`#da6871`です。この一貫性により、パレットトークンを直接使用しても安全で、新しいスキームの作成も容易になります。

### パレットカラーの注入方法

`ColorSchemeProvider`コンポーネント（`src/components/color-scheme-provider.astro`）がアクティブなカラースキームを読み取り、ビルド時に`:root`にCSSカスタムプロパティを注入します：

```css
:root {
  --zd-bg: #282a36;
  --zd-fg: #f8f8f2;
  --zd-cursor: #f8f8f2;
  --zd-sel-bg: #44475a;
  --zd-sel-fg: #ffffff;
  --zd-0: #21222c;   /* パレットスロット 0（Black） */
  --zd-1: #ff5555;   /* パレットスロット 1（Red） */
  /* ... --zd-15 まで続く */
}
```

これらの`--zd-*`プロパティがすべての基準値です。セマンティックトークン、コンポーネントトークン、Tailwindユーティリティ — すべてがこれらに帰結します。

## Tier 2：セマンティックトークン

`src/styles/global.css`の`@theme`ブロックが、パレットプロパティをデザイン上の意味を持つTailwind互換トークンにマッピングします：

```css
@theme {
  --color-*: initial;  /* Tailwindデフォルトをすべてリセット */

  /* ベース */
  --color-bg: var(--zd-bg);
  --color-fg: var(--zd-fg);
  --color-sel-bg: var(--zd-sel-bg);
  --color-sel-fg: var(--zd-sel-fg);

  /* パレット直接アクセス（p0–p15） */
  --color-p0: var(--zd-0);
  --color-p1: var(--zd-1);
  /* ... --color-p15 まで続く */

  /* セマンティックエイリアス */
  --color-surface: var(--zd-surface);
  --color-muted: var(--zd-muted);
  --color-accent: var(--zd-accent);
  --color-accent-hover: var(--zd-accent-hover);
  --color-code-bg: var(--zd-code-bg);
  --color-code-fg: var(--zd-code-fg);
  --color-success: var(--zd-success);
  --color-danger: var(--zd-danger);
  --color-warning: var(--zd-warning);
  --color-info: var(--zd-info);

  /* 検索ハイライト（専用トークン、デザイントークンパネルでライブ編集可能） */
  --color-matched-keyword-bg: var(--zd-matched-keyword-bg);
  --color-matched-keyword-fg: var(--zd-matched-keyword-fg);
}
```

`@theme`に登録されると、標準のTailwindユーティリティクラスとして使用できます：`bg-surface`、`text-accent`、`border-muted`など。

### セマンティックトークンリファレンス

| トークン | デフォルトパレットスロット | 用途 |
|---------|--------------------------|------|
| `bg` | `--zd-bg`（p9） | ページ背景 |
| `fg` | `--zd-fg`（p11） | メインテキスト |
| `surface` | `p0`（ダークサーフェス） | パネル/サイドバーのサーフェス |
| `muted` | `p8`（ミュート） | ミュートテキスト、ボーダー、コメント |
| `accent` | `p5`（アクセント） | リンク、アクティブ状態、CTA |
| `accent-hover` | `p14`（アクセントホバー） | accentのホバー状態 |
| `sel-bg` | `--zd-sel-bg` | 選択時の背景 |
| `sel-fg` | `--zd-sel-fg` | 選択時の前景 |
| `code-bg` | `p10`（サーフェス） | コードブロック背景 |
| `code-fg` | `p11`（テキストプライマリ） | インラインコードテキスト |
| `success` | `p2`（成功） | 成功状態、確認 |
| `danger` | `p1`（危険） | エラー、破壊的操作 |
| `warning` | `p3`（警告） | 警告メッセージ、Admonition、find-in-pageハイライト |
| `info` | `p4`（情報） | 情報ハイライト |
| `matched-keyword-bg` | `p3`（警告ファミリー） | 検索結果の``背景 — 専用トークン、デザイントークンパネルでライブ編集可能 |
| `matched-keyword-fg` | `p11`（テキストプライマリ） | 検索結果の``前景 — `matched-keyword-bg`とペアで使用 |

### スキームごとのセマンティックオーバーライド

各カラースキームは`src/config/color-schemes.ts`の`semantic`プロパティを通じて、デフォルトのパレットスロットマッピングをオーバーライドできます。値は**パレットインデックス**（数値）または**直接のカラー文字列**のいずれかです：

```ts
"My Custom Scheme": {
  // ...palette, background, foreground...
  semantic: {
    accent: 6,              // palette[6]を使用 — カラー値の重複なし
    accentHover: 14,         // palette[14]を使用
    surface: "#f4efdd",      // 直接のカラー文字列（パレットにない色）
  },
},
```

カラー文字列を繰り返す代わりにパレットインデックスを使用することで、重複を排除し、パレットカラーが変更された際（例：[Design Token Panel](./design-token-panel.mdx)経由）にセマンティックカラーが同期されるようになります。

同じ`number | string`型（`ColorRef`と呼ばれます）は`cursor`、`selectionBg`、`selectionFg`でもサポートされています：

```ts
"My Theme": {
  background: "#1a1a2e",
  foreground: "#e0e0e0",
  cursor: 6,            // カラーを重複させる代わりにpalette[6]を使用
  selectionBg: "#3a3a5e",
  selectionFg: 15,       // palette[15]を使用
  palette: [...],
  shikiTheme: "one-dark-pro",
},
```

解決ロジックは`src/config/color-scheme-utils.ts`にあり、各プロパティは明示的に設定されていない場合、デフォルトのパレットスロットにフォールバックします。

### 検索とハイライトのトークン（役割を分離）

ハイライトの役割は意図的に専用セマンティックトークンに分離されています。無関係なハイライトUI間でひとつのトークンを使い回すのはアンチパターンです。

- `matched-keyword-bg` / `matched-keyword-fg` は検索パネルの``要素に使われます。別の役割の`color-mix()`ではなく専用トークンのため、[デザイントークンパネル](./design-token-panel.mdx)のスウォッチがハイライト色の唯一のソースになります。パネルで見えている色＝実際のハイライト色です。
- `warning` はAdmonition（`:::warning`）、find-in-page（`.find-match`、`.find-match-active`）など、意味的に _警告_ にあたるUIで使います。**新しいUIクロム向けのハイライトに`warning`を使い回してはいけません**。

新しいハイライトの役割が出てきたとき（新種の``、新しいピル、新しいコールアウト）は、既存の役割過多なトークンに載せるのではなく、専用のセマンティックトークンを追加してください。プロダクトに現れるハイライト色はどれも、パネルのスウォッチに1対1で対応するべきです。

## Tier 3：コンポーネントトークン

一部のコンポーネントは、Tier 2のセマンティックトークンを参照する独自のカラー変数を定義しています。これらは内部的な実装の詳細です。

### コンテンツタイポグラフィ

`.zd-content`クラスはセマンティックトークンを使用した直接的な要素スタイリングを提供します（外部タイポグラフィプラグイン不要）：

```css
.zd-content {
  color: var(--color-fg);
  font-size: var(--text-body);
  line-height: var(--leading-relaxed);
}

.zd-content :where(a) {
  color: var(--color-accent);
}

.zd-content :where(code:not(pre code)) {
  color: var(--color-code-fg);
  background-color: var(--color-code-bg);
}

.zd-content :where(li::marker) {
  color: var(--color-muted);
}
/* ... */
```

Tier 3のトークンはコンポーネント内部のものです。独自のUIを構築する際は、Tier 2のセマンティックトークンまたはTier 1のパレットトークンを直接使用してください。

## カラートークンの使い方

### セマンティックトークンを優先

標準的なUIパターンにはセマンティックトークンを使用します：

```html
<!-- テキスト -->
メインテキスト
補助テキスト
リンク

<!-- 背景 -->
ページ背景
パネルやサイドバー

<!-- ボーダー -->
ボーダー付き要素
```

### 必要に応じてパレットトークンにフォールバック

適切なセマンティックトークンがない場合は`p0`〜`p15`を使用します — バッジ、装飾要素、ステータスインジケーターなどに：

```html
エラーテキスト（赤）
成功テキスト（緑）
警告テキスト（黄）
情報テキスト（青）
```

## カラースキーム

アクティブなカラースキームを変更するには、`src/config/settings.ts`を編集します：

```ts

  colorScheme: "Default Dark",  // ここを変更
  siteName: "zudo-doc",
  // ...
};
```

### デフォルトテーマ

zudo-docにはライトテーマとダークテーマのデフォルトが含まれています。利用可能なスキームは`src/config/color-schemes.ts`を参照してください。

## カスタムカラースキームの追加

`src/config/color-schemes.ts`の`colorSchemes`オブジェクトに新しいエントリを追加します：

```ts
"My Theme": {
  background: "#1a1a2e",
  foreground: "#e0e0e0",
  cursor: "#e0e0e0",
  selectionBg: "#3a3a5e",
  selectionFg: "#e0e0e0",
  palette: [
    "#16213e", "#e74c3c", "#2ecc71", "#f39c12",  // 0-3: Black, Red, Green, Yellow
    "#3498db", "#9b59b6", "#1abc9c", "#ecf0f1",  // 4-7: Blue, Magenta, Cyan, White
    "#2c3e50", "#e67e73", "#55d98d", "#f5b041",  // 8-11: Bright Black–Yellow
    "#5dade2", "#bb8fce", "#48c9b0", "#fdfefe",  // 12-15: Bright Blue–White
  ],
  shikiTheme: "one-dark-pro",
  // オプション：セマンティックのデフォルトをオーバーライド
  semantic: {
    muted: "#7f8c8d",
    surface: "#1f1f3a",
  },
},
```

`ColorScheme`インターフェースに必要なプロパティ：

- `background`、`foreground` — ベースカラー文字列
- `cursor`、`selectionBg`、`selectionFg` — `ColorRef`（パレットインデックスまたはカラー文字列）
- `palette` — 16要素のタプル（カラースロット 0〜15）
- `shikiTheme` — シンタックスハイライト用のShikiテーマ名
- `semantic`（オプション）— `ColorRef`値（パレットインデックスまたはカラー文字列）によるデフォルトパレットスロットマッピングのオーバーライド

## やってはいけないこと

**Tailwindデフォルトを使わない** — `initial`にリセットされています：

```html
<!-- NG -->
色が表示されない

<!-- OK -->
正しく動作する
```

**16進数値をハードコードしない** — テーマ切り替えが壊れます：

```html
<!-- NG -->
テーマ切り替えで壊れる

<!-- OK -->
どのテーマにも適応する
```

**Tier 3の変数を自分のコンポーネントで参照しない**：

```css
/* NG */
.my-component {
  color: var(--tw-prose-links);
}

/* OK */
.my-component {
  color: var(--color-accent);
}
```

---

# リファレンス

> Source: /pj/zudo-doc/ja/docs/reference

zudo-docのコンポーネント、デザインシステム、カラーアーキテクチャに関する技術リファレンスです。

---

# ナビゲーション構造の設計

> Source: /pj/zudo-doc/ja/docs/getting-started/structuring-navigations

## 概要

zudo-doc は **3 階層のナビゲーション構造** でコンテンツを整理します。

1. **ヘッダーナビゲーション** — サイト全体に表示される、最も広い最上位カテゴリ
2. **サイドバー** — 各ヘッダーナビセクション内の次のレベルの分類
3. **サイドバーのネストカテゴリ** — サイドバーセクション内の詳細なサブカテゴリ

各レベルはスコープを絞り込みます。ヘッダーはサイトの全体像を示し、サイドバーはセクションを論理的なグループに分け、ネストカテゴリは必要に応じて細かい構造を追加します。

## ファイル構造 = ナビゲーション構造

zudo-doc では、**ファイルとディレクトリの構造がそのままナビゲーションになります**。別途ナビゲーション設定を管理する必要はありません。サイドバーは `src/content/docs/` のディレクトリツリーから自動生成され、ヘッダーナビの各項目は `categoryMatch` でトップレベルディレクトリに対応します。

つまり、ファイルツリーを見るだけでサイト全体のナビゲーションを把握できます。リポジトリを読む人間にとっても、コンテンツを生成する AI ツールにとっても、同じように直感的です。

**ファイル構造とナビゲーション構造を密に結合させてください。** サイドバーカテゴリ「Hardware」が必要なら `hardware/` ディレクトリを作成します。ヘッダーナビに「Guides」の項目が必要なら `guides/` ディレクトリを作成し `categoryMatch: "guides"` を設定します。ディレクトリ名、URL パス、ナビゲーションのラベルはすべて対応させるのが理想です。

この密結合が推奨される理由は以下の通りです。

- **予測可能性** — ファイルの配置場所を見れば、ナビゲーションのどこに表示されるかが常にわかる
- **乖離がない** — 実際のコンテンツと同期がずれる別の設定ファイルが存在しない
- **AI フレンドリー** — AI ツールがディレクトリ構造の規約に従うだけで、正確なナビゲーションを生成できる

zudo-doc は複雑なケースに対応する高度な設定（カスタムサイドバーラベル、ソート順の上書き、ネストドロップダウンなど）もサポートしていますが、デフォルトの動作 — ディレクトリがカテゴリに、ファイルがページになる — でほとんどのケースに対応できます。まずはシンプルに始めて、デフォルトの対応では不十分な場合にのみ複雑さを追加してください。

## ヘッダーナビゲーションのルール

ヘッダーナビゲーションは最上位のレベルです。サイトの主要セクションを定義する、最も広いカテゴリのみを含めてください。

- **簡潔にする** — 3〜6 項目を目安にしましょう。それ以上はユーザーを圧倒し、ヘッダーが煩雑になります。
- **ドロップダウンは控えめに** — 密接に関連するセクションをまとめる場合のみ使用します（例：「学習」に「ガイド」と「コンポーネント」を含める）。
- **各項目はコンテンツディレクトリに対応** — 設定の `categoryMatch` フィールドがヘッダー項目をそのセクションのサイドバーコンテンツにリンクします。

設定の詳細は [ヘッダーナビゲーション](../guides/header-navigation.mdx) を参照してください。

### ヘッダー設定の例

```ts
// src/config/settings.ts

  headerNav: [
    { label: "Getting Started", path: "/docs/getting-started", categoryMatch: "getting-started" },
    {
      label: "Learn",
      path: "/docs/guides",
      categoryMatch: "guides",
      children: [
        { label: "Guides", path: "/docs/guides", categoryMatch: "guides" },
        { label: "Components", path: "/docs/components", categoryMatch: "components" },
      ],
    },
    { label: "Reference", path: "/docs/reference", categoryMatch: "reference" },
  ],
};
```

## サイドバー構造のルール

サイドバーは、各ヘッダーナビセクション内の次のレベルの分類を提供します。ディレクトリ構造から自動的に生成されます。

- **カテゴリにはディレクトリを使う** — 各ディレクトリが折りたたみ可能なサイドバーグループになります。
- **各カテゴリディレクトリに `index.mdx` を用意する** — カテゴリのランディングページとして機能し、`sidebar_position` を設定します。
- **ネストは 2〜3 レベルまで** — 深いネストはナビゲーションしづらく、コンテンツの再編成が必要なサインです。
- **すべてのページに `sidebar_position` を設定する** — アルファベット順のデフォルトに頼らず、予測可能な順序を確保します。

設定の詳細は [サイドバー](../guides/sidebar.mdx) を参照してください。

### ディレクトリからサイドバーへのマッピング

```
src/content/docs/guides/        ← サイドバーカテゴリ「Guides」
├── index.mdx                   ← カテゴリランディング（sidebar_position: 0）
├── configuration.mdx           ← sidebar_position: 1
├── sidebar.mdx                 ← sidebar_position: 2
└── header-navigation.mdx       ← sidebar_position: 3
```

各 `.mdx` ファイルがサイドバー項目として表示されます。サブディレクトリはネストされた折りたたみ可能なカテゴリになります。

## 具体的な実例

**ゲーム攻略 Wiki** を構築する場合のナビゲーション構造です。

### ナビゲーション計画

```
ヘッダーナビ:
├── ホーム
├── プラットフォーム        ← ドロップダウン
│   ├── Xbox
│   ├── PlayStation
│   └── Nintendo
├── ジャンル                ← ドロップダウン
│   ├── RPG
│   ├── アクション
│   └── ストラテジー
└── コミュニティ
```

ユーザーが「プラットフォーム」ドロップダウンで「Xbox」をクリックすると、サイドバーは以下のように表示されます。

```
サイドバー（Xbox セクション）:
├── 概要（index）
├── ハードウェア
│   ├── Xbox Series X
│   ├── Xbox Series S
│   └── アクセサリ
├── ゲーム
│   ├── Halo Infinite
│   ├── Forza Horizon 5
│   └── Starfield
└── サービス
    ├── Game Pass
    └── Xbox Live
```

### ゲーム Wiki のヘッダー設定

`categoryMatch` の値は **単一のトップレベルディレクトリ名** である必要があります。フレームワークは現在の URL の最初のパスセグメントのみを照合してアクティブ状態を解決します。

```ts
// src/config/settings.ts

  headerNav: [
    { label: "Home", path: "/docs/home", categoryMatch: "home" },
    {
      label: "Platforms",
      path: "/docs/xbox",
      categoryMatch: "xbox",
      children: [
        { label: "Xbox", path: "/docs/xbox", categoryMatch: "xbox" },
        { label: "PlayStation", path: "/docs/playstation", categoryMatch: "playstation" },
        { label: "Nintendo", path: "/docs/nintendo", categoryMatch: "nintendo" },
      ],
    },
    {
      label: "Genres",
      path: "/docs/rpg",
      categoryMatch: "rpg",
      children: [
        { label: "RPG", path: "/docs/rpg", categoryMatch: "rpg" },
        { label: "Action", path: "/docs/action", categoryMatch: "action" },
        { label: "Strategy", path: "/docs/strategy", categoryMatch: "strategy" },
      ],
    },
    { label: "Community", path: "/docs/community", categoryMatch: "community" },
  ],
};
```

### ゲーム Wiki のディレクトリ構造

各プラットフォームとジャンルが独自のトップレベルディレクトリを持つことで、`categoryMatch` が URL の最初のセグメントと正しく対応します。

```
src/content/docs/
├── home/
│   └── index.mdx
├── xbox/
│   ├── index.mdx                  ← 「概要」
│   ├── hardware/
│   │   ├── index.mdx
│   │   ├── xbox-series-x.mdx
│   │   ├── xbox-series-s.mdx
│   │   └── accessories.mdx
│   ├── games/
│   │   ├── index.mdx
│   │   ├── halo-infinite.mdx
│   │   ├── forza-horizon-5.mdx
│   │   └── starfield.mdx
│   └── services/
│       ├── index.mdx
│       ├── game-pass.mdx
│       └── xbox-live.mdx
├── playstation/
│   └── index.mdx
├── nintendo/
│   └── index.mdx
├── rpg/
│   └── ...
├── action/
│   └── ...
├── strategy/
│   └── ...
└── community/
    └── index.mdx
```

## よくある間違い

ナビゲーション設定で避けるべき落とし穴です。

- **ヘッダーに詰め込みすぎる** — ヘッダーには広いカテゴリだけを置きましょう。10 個以上の項目がある場合、ほとんどはサイドバーに属します。
- **深すぎるサイドバーのネスト** — 3 レベル以上のネストはコンテンツを見つけにくくします。別のヘッダーナビセクションに分割してフラットにしましょう。
- **無関係なトピックの混在** — 各サイドバーセクションは一貫したエリアをカバーするべきです。「ハードウェア」と「コミュニティイベント」が同じサイドバーにある場合は、ヘッダーカテゴリを見直しましょう。
- **`sidebar_position` の未設定** — 設定しないとページがアルファベット順にソートされ、混乱を招くことが多いです。予測可能なナビゲーションのために必ず `sidebar_position` を設定しましょう。
- **カテゴリディレクトリに `index.mdx` がない** — index がないとカテゴリにランディングページがなく、サイドバーに正しく表示されない場合があります。
- **`categoryMatch` に複数セグメントの値を使う**（例：`"platforms/xbox"`）— `categoryMatch` は単一のトップレベルディレクトリ名でなければなりません。複数セグメントの値はヘッダーナビのアクティブ状態ハイライトを壊します。

## AI ツールによるセットアップのヒント

AI ツールで zudo-doc のサイト構造を生成する際は、以下のルールに従って一貫した結果を得てください。

- **階層構造を厳密に守る** — ヘッダーナビは広いカテゴリ、サイドバーはサブカテゴリ、ネストディレクトリはさらなる詳細。レベルを飛ばさないでください。
- **ヘッダーナビには広いカテゴリのみ** — 個別のページをヘッダーに追加したくなる誘惑に負けないでください。それはサイドバーの役割です。
- **`categoryMatch` の値を実際のディレクトリ名と一致させる** — `categoryMatch: "guides"` は `src/content/docs/guides/` ディレクトリに対応する必要があります。
- **すべてのカテゴリディレクトリに `index.mdx` を必ず作成する** — カテゴリに適切なランディングページとサイドバーエントリを確保します。
- **すべてのページとインデックスに `sidebar_position` を設定する** — AI ツールが最も忘れやすいポイントで、予測不可能な順序につながります。
- **ディレクトリとファイル名にケバブケースを使う** — 一貫した命名でプラットフォーム間の大文字小文字の問題を回避します。

---

# Details

> Source: /pj/zudo-doc/ja/docs/components/details

`` を使用して、折りたたみ可能なコンテンツセクションを作成できます。このコンポーネントはグローバルに利用可能で、インポートは不要です。

## 基本的な使い方

このコンテンツはデフォルトでは非表示で、ユーザーがサマリーをクリックすると表示されます。

```mdx

このコンテンツはデフォルトでは非表示で、ユーザーがサマリーをクリックすると表示されます。

```

## デフォルトタイトル

`title` プロップを指定しない場合、サマリーのテキストはデフォルトで「Details」になります。

この折りたたみセクションはデフォルトのタイトルを使用しています。

```mdx

この折りたたみセクションはデフォルトのタイトルを使用しています。

```

## リッチコンテンツ

`` ブロック内には、コードブロック、リスト、その他のコンポーネントなど、あらゆる MDX コンテンツを含めることができます。

以下はサンプル設定です： ```ts export default { site: "https://example.com", output: "static", }; ``` ポイント： - `site` フィールドはベース URL を設定します - `output` フィールドはビルドモードを制御します - すべてのフィールドは適切なデフォルト値を持つオプションです

````mdx

以下はサンプル設定です：

```ts

  site: "https://example.com",
  output: "static",
};

```

ポイント：

- `site` フィールドはベース URL を設定します
- `output` フィールドはビルドモードを制御します
- すべてのフィールドは適切なデフォルト値を持つオプションです

````

## プロップ

| プロップ | 型 | デフォルト | 説明 |
|------|------|---------|-------------|
| `title` | string | `"Details"` | クリック可能なサマリーテキスト |

---

# コントリビューション

> Source: /pj/zudo-doc/ja/docs/getting-started/contribution

## 背景

zudo-docは[Takazudo](https://x.com/Takazudo)がドキュメンテーションフレームワークとして作成しました。もともとは個人利用のために構築されたもので、複数のプロジェクトで繰り返し必要になるワークフローやデザインの好みに合わせた、Docusaurusの軽量な代替として開発されました。

時間の経過とともに、16色ターミナルパレットシステム、MDXコンテンツコレクション、i18nサポート、Claude Code連携などの機能を備えた独立したフレームワークへと成長しました。

## 開発

このプロジェクトのソースコードの大部分は[Claude Code](https://claude.com/claude-code)の助けを借りて書かれています。フレームワークはMITライセンスの下で公開されています。

## メンテナンス

このプロジェクトはベストエフォートベースでメンテナンスされています。積極的なメンテナンスやコントリビューションの徹底的なレビューには限りがある場合があります。

公式サポートを待つよりも、**リポジトリをフォーク**して必要な変更を自分で実装することをお勧めします。AI時代においては、フォークしてカスタマイズする方がアップストリームの変更を待つよりも速いことが多いです。

## 貢献方法

貢献したい場合は：

1. GitHubでリポジトリをフォーク
2. `main`からトピックブランチを作成
3. 変更を加え、`pnpm b4push`がパスすることを確認（型チェック、ビルド、E2Eテスト、フォーマットチェック）
4. 変更内容と理由を明確に記述してプルリクエストを作成

バグ報告や機能リクエストは[GitHub Issues](https://github.com/zudolab/zudo-doc/issues)で受け付けています。

## ライセンス

zudo-docは[MITライセンス](https://github.com/zudolab/zudo-doc/blob/main/LICENSE)の下で公開されています。

## 著者

- **高津戸 壮** ([@Takazudo](https://x.com/Takazudo))

---

# ヘッダーナビゲーション

> Source: /pj/zudo-doc/ja/docs/guides/header-navigation

zudo-docはDocusaurusにインスパイアされたナビゲーション階層をサポートしています：

- **ヘッダーナビゲーション** — サイトヘッダーのトップレベルタブ。オプションでドロップダウンメニューを含む
- **サイドバーカテゴリ** — サイドバーの折りたたみ可能なグループ
- **サイドバーアイテム** — カテゴリ内の個別ページ

このページは**左側のタブ**について説明しています。右側クラスタ(テーマ切替・GitHub リンクなど)の設定は別ページ [ヘッダー右側アイテム](./header-right-items.mdx) を参照してください。

## 設定

`src/config/settings.ts`でヘッダーナビゲーションアイテムを定義します。アイテムはフラットリンクまたはネストされた子を持つドロップダウン親のいずれかです：

```ts

  // ...
  headerNav: [
    // フラットリンク（ドロップダウンなし）
    { label: "Getting Started", labelKey: "nav.gettingStarted", path: "/docs/getting-started", categoryMatch: "getting-started" },

    // 子を持つドロップダウン親
    {
      label: "Learn",
      labelKey: "nav.learn",
      path: "/docs/guides",
      categoryMatch: "guides",
      children: [
        { label: "Guides", labelKey: "nav.guides", path: "/docs/guides", categoryMatch: "guides" },
        { label: "Components", labelKey: "nav.components", path: "/docs/components", categoryMatch: "components" },
      ],
    },

    { label: "Reference", labelKey: "nav.reference", path: "/docs/reference", categoryMatch: "reference" },
  ],
};
```

## プロパティ

### `HeaderNavItem`

| プロパティ | 型 | 説明 |
|----------|------|-------------|
| `label` | string | ヘッダーに表示されるテキスト |
| `labelKey` | string（オプション） | 翻訳が利用可能な場合に`label`をオーバーライドするi18n翻訳キー |
| `path` | string | リンク先のURLパス |
| `categoryMatch` | string（オプション） | このヘッダータブをサイドバーカテゴリにリンク |
| `children` | `HeaderNavChildItem[]`（オプション） | ドロップダウンメニューとして表示される子ナビゲーションアイテム（1階層のみ） |

### `HeaderNavChildItem`

子アイテムは`HeaderNavItem`と同じプロパティを使用しますが、独自の`children`を持つことはできません。これにより型レベルで1階層のネストが強制されます。

| プロパティ | 型 | 説明 |
|----------|------|-------------|
| `label` | string | ドロップダウンに表示されるテキスト |
| `labelKey` | string（オプション） | i18n翻訳キー |
| `path` | string | リンク先のURLパス |
| `categoryMatch` | string（オプション） | この子アイテムをサイドバーカテゴリにリンク |

### `labelKey`

`labelKey`プロパティはヘッダーナビゲーションラベルのローカライズを可能にします。設定すると、zudo-docは現在のロケールの翻訳ファイルでキーを検索し、翻訳された文字列を`label`の代わりに使用します。翻訳が見つからない場合は`label`がフォールバックとして使用されます。

翻訳キーは`nav.*`名前空間規約に従います（例：`"nav.gettingStarted"`、`"nav.guides"`）。

### `categoryMatch`

`categoryMatch`プロパティはヘッダータブを特定のサイドバーカテゴリに接続します。`categoryMatch`を持つヘッダータブがアクティブな場合、サイドバーはそのカテゴリ内のページのみを表示するようにフィルタリングされます。

例えば、`categoryMatch: "guides"`はタブを`guides/`コンテンツディレクトリにリンクします。ユーザーが`/docs/guides/`配下のページに移動すると、「Guides」タブがアクティブになり、サイドバーにはguidesカテゴリのみが表示されます。

子アイテムにも`categoryMatch`を設定できます。例えば、子に`categoryMatch: "components"`を設定すると、`/docs/components/`にアクセスした際に親ドロップダウンがアクティブになり、サイドバーがコンポーネントセクションにフィルタリングされます。

## ドロップダウンの動作

`children`を持つアイテムはドロップダウンメニューとして表示されます。親アイテム自体は引き続きクリック可能なリンクとして機能し、クリックすると`path`に遷移します。ドロップダウンは関連するサブページへのクイックアクセスを提供します。

- **デスクトップ**：ホバーで開き、マウスがメニュー領域から離れると閉じます。小さなシェブロンがドロップダウンを示します。
- **キーボード**：トリガーがフォーカスを受けた時に開きます（`focus-within`経由）。Escapeキーで閉じます。マウスなしでも完全にアクセス可能です。
- **モバイル**：ネストアイテムはモバイルサイドバーメニューで展開可能なグループとして表示され、シェブロンをタップして子を展開/折りたたみできます。
- **オーバーフロー**：ブラウザウィンドウが狭くドロップダウンの親がオーバーフロー「...」メニューに移動された場合、子アイテムはインデントされたサブアイテムとして表示されます。

## アクティブ状態

現在のページURLがアイテムの`path`で始まる場合、そのヘッダーナビゲーションアイテムがアクティブとみなされます。現在のページが子アイテムの`path`にマッチする場合、親アイテムもアクティブとして表示されます。

例えば、`/docs/components/admonitions`にアクセスすると、`/docs/components`が子アイテムの一つにマッチするため「Learn」ドロップダウンがアクティブになります。

## モバイル動作

小さな画面（`< 1024px`）では、デスクトップヘッダーナビゲーションは非表示になります。モバイルではサイドバートグルですべてのナビゲーションにアクセスできます。ネストナビゲーションアイテムはモバイルサイドバーで展開可能なグループとして表示されます。シェブロンをタップして子を展開/折りたたみできます。

---

# サイドバーフィルター

> Source: /pj/zudo-doc/ja/docs/guides/sidebar-filter

## 概要

サイドバーフィルターは、サイドバーの上部に表示されるテキスト入力フィールドで、入力に応じてナビゲーション項目をリアルタイムでフィルタリングします。大規模なドキュメントサイトで、サイドバーツリー全体をスクロールせずにページをすばやく見つけるのに役立ちます。

サイドバーフィルターは `create-zudo-doc` で作成されたプロジェクトではデフォルトで有効です。

## 仕組み

フィルター入力はサイドバーの上部、ナビゲーションツリーの上に表示されます。入力すると:

- カテゴリ名と個々のページタイトルの両方がクエリと照合されます
- 大文字小文字を区別しません
- カテゴリ名がマッチした場合、すべての子ページが表示されます
- 子ページのみがマッチした場合、親カテゴリはマッチした子ページだけを表示します
- フィルタリング中、マッチしたカテゴリはすべて自動的に展開されます
- 入力をクリアすると、完全なサイドバーツリーが復元されます

## キーボードショートカット

`Ctrl+/`（Windows/Linux）または `Cmd+/`（macOS）を押すと、ページのどこからでもフィルター入力にフォーカスできます。これはサイドバーが表示されている場合（デスクトップビューポートまたはモバイルサイドバーが開いている場合）に機能します。

## 有効化・無効化

### create-zudo-doc の場合

サイドバーフィルターはデフォルトで有効です。プロジェクト作成時に無効にするには:

```bash
pnpm create zudo-doc my-docs --no-sidebar-filter
```

明示的に有効にするには:

```bash
pnpm create zudo-doc my-docs --sidebar-filter
```

### 既存プロジェクトの場合

サイドバーフィルターは `SidebarTree` Preact コンポーネント（`src/components/sidebar-tree.tsx`）に組み込まれています。サイドバーの一部として常にレンダリングされ、`settings.ts` に個別の切り替え設定はありません。スキャフォールドされたプロジェクトから削除するには、コンポーネントを直接変更する必要があります。

ほとんどのドキュメントサイトでは、ページ数が少なくてもサイドバーフィルターは便利です。コンテンツが数十ページを超えると不可欠になります。

---

# CJK対応マークダウン

> Source: /pj/zudo-doc/ja/docs/reference/cjk-friendly

## 問題

CommonMark には、CJK（中国語・日本語・韓国語）の約物に隣接した強調（太字・斜体）が正しく動作しないという既知の問題があります。次のようなマークダウンを考えてみましょう：

```md
**テスト。**テスト
```

修正なしでは、これは `**テスト。**テスト` とそのまま文字列として出力されてしまいます — 太字のマーカーが認識されません。同じ問題は他のCJK約物や斜体（`*` および `_`）にも発生します。

## 原因

CommonMark の仕様では、強調のパースにおいて特定の文字を「Unicode 約物」として分類しています。`。`（句点）などのCJK約物もこのカテゴリに該当します。仕様のフランキングルールにより、強調デリミタの直後に約物が来る場合、開始デリミタとして認識されなくなります。その結果、閉じる `**` が開く `**` と対応できなくなります。

影響を受ける文字には、以下のようなものが含まれます（これらに限りません）：

| 文字 | 説明 |
|------|------|
| `。` | 句点（全角ピリオド） |
| `、` | 読点（全角コンマ） |
| `」` | 鉤括弧（閉じ） |
| `）` | 全角括弧（閉じ） |
| `』` | 二重鉤括弧（閉じ） |
| `【` の対応 `】` | 隅付き括弧（閉じ） |
| `《` の対応 `》` | 二重山括弧（閉じ） |

`**`、`*`、`__`、`_` の直前にCJKの閉じ約物が来ると、この問題が発生します。

## remark-cjk-friendly による修正

[`remark-cjk-friendly`](https://github.com/tats-u/remark-cjk-friendly) プラグインは、`micromark` の強調パースルールにパッチを当て、CJK約物をフランキング検出において Unicode 約物として**扱わない**ようにします。これにより、CJKテキストに隣接した太字・斜体が直感的に期待通り機能するようになります。

### 修正前後の比較

入力マークダウン：

```md
**テスト。**テスト
```

| | 出力 |
|---|------|
| プラグインなし | `**テスト。**テスト`（文字列としてそのまま表示） |
| プラグインあり | **テスト。**テスト（太字が正しく適用される） |

同じ修正は斜体マーカーや他のCJK約物にも適用されます。

## 有効化・無効化

プラグインは `src/config/settings.ts` の `cjkFriendly` 設定で制御します：

```ts

  // ...
  cjkFriendly: true,   // false に設定すると無効
};
```

`cjkFriendly` が `true`（デフォルト）の場合、`remark-cjk-friendly` が MDX の remark プラグインチェーンに自動的に追加されます。コンテンツが英語のみで、標準の CommonMark 動作を使いたい場合は `false` に設定してください。

[セットアッププリセットジェネレーター](/ja/docs/getting-started/setup-preset-generator)や [create-zudo-doc CLI](/ja/docs/reference/create-zudo-doc) でプロジェクトを作成する際にも、`--cjk-friendly` / `--no-cjk-friendly` オプションで設定できます。

---

# ヘッダー右側アイテム

> Source: /pj/zudo-doc/ja/docs/guides/header-right-items

ヘッダーの右側 — 検索、テーマ切替、言語スイッチャー、バージョンスイッチャー、GitHub リンク、Design Token / AI Chat トリガー — は `settings.headerRightItems` という 1 つの配列からレンダリングされます。各エントリは discriminated union で、配列の順番どおりに描画されます。

左側のタブは [ヘッダーナビゲーション](./header-navigation.mdx) で設定します。どちらも `src/config/settings.ts` に定義しますが、互いに独立しています。

## デフォルト設定

```ts

  // ...
  githubUrl: "https://github.com/zudolab/zudo-doc",
  headerRightItems: [
    { type: "trigger", trigger: "design-token-panel" },
    { type: "trigger", trigger: "ai-chat" },
    { type: "component", component: "version-switcher" },
    { type: "component", component: "github-link" },
    { type: "component", component: "theme-toggle" },
    { type: "component", component: "language-switcher" },
  ],
};
```

組込みの `Search` コンポーネントは常にクラスタ末尾に描画され、この配列では構成しません。

## アイテム種別

### `component`

組み込みの UI 要素を参照します。対応する機能フラグが無効なら自動的にスキップされます。

| コンポーネント | 機能フラグ |
|---|---|
| `theme-toggle` | `colorMode` |
| `language-switcher` | `locales`(少なくとも 1 つの非デフォルトロケールが必要) |
| `version-switcher` | `versions` |
| `github-link` | `githubUrl` |

```ts
{ type: "component", component: "github-link" }
```

機能を無効化すればエントリは黙って除外されるので、配列に残したままでも問題ありません。

### `trigger`

組み込みのモーダルやパネルを開きます。

| トリガー | 機能フラグ |
|---|---|
| `design-token-panel` | `designTokenPanel`(互換エイリアス `colorTweakPanel`) |
| `ai-chat` | `aiAssistant` |

```ts
{ type: "trigger", trigger: "ai-chat" }
```

### `link`

任意の外部/内部リンクをアイコン付きで描画します。

```ts
{
  type: "link",
  href: "https://discord.example",
  ariaLabel: "Discord",
  icon: "github", // 現在同梱されているアイコンは "github" のみ
}
```

外部 URL は自動的に新しいタブで開きます。

### `html`

任意のマークアップを差し込むためのエスケープハッチです。

```ts
{ type: "html", html: 'beta' }
```

文字列がそのまま出力されるため、使いどころは限定してください。

## カスタマイズ例

### GitHub アイコンをあなたのリポジトリへ向ける

トップレベルの `githubUrl` を書き換えるだけで済みます。`github-link` コンポーネントはこの値を読むので、配列側に URL を書き足す必要はありません。

```ts

  githubUrl: "https://github.com/your-org/your-repo",
};
```

`githubUrl: false` を指定すると、配列を編集せずにアイコンだけ消せます。

### アイテムを外す

機能フラグでの非表示ではなく、配列から該当エントリを削除してください。たとえば AI chat トリガーを隠すなら:

```ts
headerRightItems: [
  { type: "trigger", trigger: "design-token-panel" },
  // { type: "trigger", trigger: "ai-chat" },  // 削除
  { type: "component", component: "version-switcher" },
  { type: "component", component: "github-link" },
  { type: "component", component: "theme-toggle" },
  { type: "component", component: "language-switcher" },
],
```

### カスタムリンクを追加する

```ts
headerRightItems: [
  // ...既存のアイテム
  {
    type: "link",
    href: "https://discord.gg/your-server",
    ariaLabel: "Discord",
    icon: "github", // 他アイコン同梱までの暫定
  },
],
```

## 並び順

配列に書いた順にレンダリングされます。クラスタは右寄せなので、最初のエントリがナビ寄り、末尾のエントリがビューポート端寄りに配置されます。

---

# 数式

> Source: /pj/zudo-doc/ja/docs/components/math-equations

設定で `math` が有効になっている場合（デフォルト：`true`）、KaTeX を使用して数式をレンダリングできます。

## インライン数式

テキスト内に数式を埋め込むには、単一のドル記号を使用します。

数式 $E = mc^2$ はインラインで表示されます。

```mdx
数式 $E = mc^2$ はインラインで表示されます。
```

## ブロック数式

中央揃えのディスプレイ数式をレンダリングするには、二重のドル記号を使用します。

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

```mdx
$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$
```

## フェンスドコードブロック

`math` 言語識別子を指定したフェンスドコードブロックを使用します。

```math
\nabla \times \mathbf{E} = -\frac{\partial \mathbf{B}}{\partial t}
```

````mdx
```math

\nabla \times \mathbf{E} = -\frac{\partial \mathbf{B}}{\partial t}

```
````

## 設定

数式サポートは `src/config/settings.ts` の `math` 設定で制御されます：

```ts

  // ...
  math: true, // デフォルトで有効
};
```

## その他の例

### 二次方程式の解の公式

$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$

```mdx
$$
x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}
$$
```

### 総和

$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$

```mdx
$$
\sum_{i=1}^{n} i = \frac{n(n+1)}{2}
$$
```

### 行列

$$
\begin{bmatrix}
a & b \\
c & d
\end{bmatrix}
\begin{bmatrix}
x \\
y
\end{bmatrix}
=

\begin{bmatrix}
ax + by \\
cx + dy
\end{bmatrix}
$$

```mdx
$$
\begin{bmatrix}
a & b \\
c & d
\end{bmatrix}
\begin{bmatrix}
x \\
y
\end{bmatrix}
=
\begin{bmatrix}
ax + by \\
cx + dy
\end{bmatrix}
$$
```

---

# サイト検索

> Source: /pj/zudo-doc/ja/docs/guides/search

## 検索の仕組み

zudo-docは全文サイト検索に[MiniSearch](https://lucaong.github.io/minisearch/)を使用しています。コンテンツファイル（タイトル、説明、本文）から検索インデックスが生成され、単一のJSONファイルとして配信されます。ブラウザがこのインデックスを読み込み、すべての検索をクライアントサイドで実行します — サーバーや外部サービスは不要です。

## 検索の使い方

検索ダイアログを開くには：

- **キーボードショートカット**：`Ctrl+K`（Windows/Linux）または`Cmd+K`（macOS）
- **検索ボタン**：ヘッダーの検索アイコンをクリック

クエリを入力すると結果が即座に表示されます。結果をクリックするとそのページに移動します。

## すべての環境で動作

検索はすべての環境で動作します：

- **開発モード**（`pnpm dev`）：検索インデックスはViteミドルウェア経由でオンザフライで生成
- **本番ビルド**（`pnpm build`）：インデックスは静的サイトとともに`search-index.json`に出力
- **Electron**：同じインデックスファイルを読み込み — 特別な処理は不要

検索をテストするためにビルドする必要はありません。`pnpm dev`ですぐに動作します。

## ページを検索から除外する

フロントマターに`search_exclude: true`、`draft: true`、または`unlisted: true`が設定されたページは、検索インデックスから自動的に除外されます。

ページを明示的に除外するには、フロントマターに`search_exclude: true`を追加します：

```mdx
---
title: My Internal Page
search_exclude: true
---
```

これは変更履歴、インポートされたコンテンツ（例：CLAUDE.md）、検索結果を煩雑にする内部専用ページなどに便利です。

## 検索機能

MiniSearchは以下を提供します：

- **ファジーマッチング**：タイポを許容（最大20%の文字差異）
- **プレフィックス検索**：入力中に結果を検出（例：「conf」は「Configuration」にマッチ）
- **フィールドブースティング**：タイトルの一致は本文の3倍、説明は2倍にランク付け
- **即時結果**：フルインデックスが一度読み込まれ、メモリ内でクエリを実行

## サーバーサイド検索（Search Worker）

大規模なドキュメントベースやプログラムによるAPIアクセスのために、zudo-docはオプションの**Search Worker**を提供しています。これはMiniSearchをサーバーサイドで実行するCloudflare Workerです。

### Search Workerを使うべき場合

組み込みのクライアントサイド検索は小〜中規模のドキュメントサイトで十分に動作します。Search Workerは以下の場合に便利です：

- **大きなインデックスサイズ** -- フルの`search-index.json`がブラウザへのダウンロードには大きすぎる場合
- **APIコンシューマー** -- ボット、CLIツール、インテグレーションがブラウザなしで検索にアクセスする必要がある場合
- **サーバーサイド処理** -- 検索インデックスをクライアントから離したい場合

### 仕組み

Search Workerはデプロイ済みのサイトから同じ`search-index.json`を取得し、5分のTTLでキャッシュします。同一のMiniSearch設定（プレフィックス、ファジー、ブースト設定）を使用するため、結果はクライアントサイド検索と一貫しています。

### 比較

| 機能                     | クライアントサイド検索（組み込み） | Search Worker              |
| ------------------------ | ---------------------------------- | -------------------------- |
| ランタイム               | ブラウザ（インメモリ）             | Cloudflare Workers         |
| セットアップ             | 不要（デフォルトで有効）           | Cloudflareアカウント + KV  |
| インデックスダウンロード | フルインデックスをブラウザに送信   | インデックスはサーバーサイドに留まる |
| 最適な用途               | 小〜中規模のドキュメント           | 大規模なドキュメント、APIコンシューマー |
| レイテンシ               | 即時（ローカル）                   | ネットワークラウンドトリップ |

セットアップ手順、APIドキュメント、デプロイの詳細については、[Search Worker APIリファレンス](/ja/docs/reference/search-worker)を参照してください。

---

# タグ

> Source: /pj/zudo-doc/ja/docs/guides/tags

## 概要

タグは、サイドバーのカテゴリが異なっていても同じトピックを扱うドキュメントページをまとめるための、**カテゴリ横断的な**仕組みです。たとえば Guides の下にあるデプロイ関連のページと、Reference にあるトラブルシューティングページの両方に `deployment` タグを付けておけば、そのトピックを探している読者は両方のページにたどり着けます。

次のような場面で使います。

- 複数のカテゴリにまたがるトピック（例: `deployment`、`i18n`、`accessibility`）。
- サイドバー上では隣り合わないが、関連性の高いページを読者に発見してもらいたいとき。
- ディレクトリ構成を変えずに補助的なナビゲーションを追加したいとき。

タグはサイドバーを**補完するもの**であり、置き換えるものではありません。サイドバーは構造を反映し、タグはトピックを反映します。

## タグを追加する

タグはページの frontmatter に文字列の配列として指定します。

```mdx
---
title: Deploying to Cloudflare Pages
sidebar_position: 3
tags: [deployment, hosting]
---
```

1 ページに付けられるタグの数に制限はありません。タグは大文字・小文字を区別する文字列なので、表記を統一しておきます（下記の「命名規則」を参照）。

## タグが表示される場所

ビルド後のサイトでは、タグは次の 3 か所に現れます。

### ページのバッジ列

タグが 1 つ以上付いたページでは、タグバッジの列が表示され、各バッジはそのタグのインデックスページへリンクします。これは `DocTags` コンポーネント（`TagNav` に `variant="page"` を指定したもの）によって描画されます。

バッジ列の表示位置は [`tagPlacement`](./configuration.mdx#tagplacement) 設定で次の 2 つから選べます。

- `"after-title"`（デフォルト） — ページタイトルの直下、本文の上にバッジ列を表示します。タグがページの概要を一目で示すラベルであり、スクロールせずに見せたいときに向いています。
- `"before-pager"` — コンテンツの末尾、前後ページャーのすぐ上にバッジ列を表示します。タグがページを読み終えたあとに参照するメタデータ的な位置づけのときに向いています。

どちらか一方だけが有効で、設定はサイト全体に適用されます。

### ホームページの「All Tags」セクション

`settings.docTags` が `true` で、かつ現在のロケールにタグ付きページが 1 つ以上存在する場合、ホームページに「All Tags」セクションが表示され、利用中のすべてのタグとそのインデックスページへのリンクが並びます。タグ付きページが 1 つもないときは、このセクションは自動的に非表示になります。

### タグインデックスとタグごとのページ

- [/ja/docs/tags/](/ja/docs/tags/) — 利用中のタグとページ数を一覧表示するグローバルなタグインデックス。
- `/ja/docs/tags/[tag]` — タグごとに 1 ページ。そのタグが付いたすべてのページを一覧表示します。

これらのルートは frontmatter から自動生成されるため、手動で作る必要はありません。

## 命名規則

タグ名を統一しておくと、タグインデックスがすっきりし、`deployment` と `Deployment` のような重複表記を避けられます。

- **小文字** — タグは表示用のテキストではなくスラッグとして扱います。
- 複数単語は **kebab-case** にする — `color-scheme` を使い、`colorScheme` や `color_scheme` は避けます。
- **短く、具体的に** — `internationalization-and-localization` より `i18n` が望ましい。
- **ロケールをまたいで一貫** — EN と JA の frontmatter で同じタグスラッグを使います（下記参照）。

新しいタグを導入する前に、[/ja/docs/tags/](/ja/docs/tags/) のインデックスを眺めて、近い意味のタグがすでに存在しないか確認します。

## i18n の挙動

タグはロケールをまたいだ**共通の識別子**であり、翻訳するラベルではありません。

- 同じタグスラッグを EN と JA の frontmatter で使います（例: 両方のファイルで `tags: [deployment]`）。
- タグインデックスはロケールごとに別々です。EN の `/docs/tags/deployment` は EN ページを一覧します。JA の `/ja/docs/tags/deployment` はまず JA に翻訳されたページを表示し、翻訳がまだ存在しないスラッグについては **EN ページにフォールバックします** — 未翻訳の EN ドキュメントもそのまま JA のタグページに表示されるため、「翻訳が無いから消える」ということは起きません。
- **タグスラッグは翻訳しません。** JA ファイルで `deployment` を `デプロイ` に置き換えると、タグが無関係な 2 つのグループに分かれ、ロケール横断のモデルが壊れます。

ロケール別の表示ラベルが欲しくなった場合は将来的な拡張課題です。現時点ではスラッグが識別子と表示ラベルを兼ねています。

## 設定

タグの表示は `src/config/settings.ts` の `docTags` 設定で制御します。有効（デフォルト）のときは、ページ下部のタグバッジ列とホームページの「All Tags」セクションが描画されます。`false` にするとこれらの表示は非表示になりますが、`/ja/docs/tags/` のインデックスや `/ja/docs/tags/[tag]` のページはビルドされ、URL から直接アクセスすればそのまま到達できます。

詳細は[Configuration](./configuration.mdx)を参照してください。

## チームプロジェクトへのスケール

著者が片手で数えきれなくなると、自由記述のタグはドリフトし始めます。zudo-doc はドキュメントベースが大きくなってもタグインデックスを整えておくためのボキャブラリ対応ガバナンスワークフローを備えています。

- [タグガバナンス](./tag-governance.mdx) — 正規ボキャブラリを整備し、`tagGovernance: "warn" | "strict"`で強制する。
- [タグ監査](./tags-audit.mdx) — `pnpm tags:audit`が unknown、deprecation、エイリアス、ニアデュプリケート、オーファンを報告する。エイリアスはバイト安定な`--fix`で書き換えられ、`--ci`で`pnpm b4push`と連携できる。
- [タグサジェスト](./tags-suggest.mdx) — 新しいページに正規タグを提案するオプション機能(`pnpm tags:suggest`)。
- [フッタータグリスト](./footer-taglist.mdx) — ボキャブラリを読者向けに公開するオプトインのフッターカラム。

## 関連する frontmatter フィールド

タグナビゲーションと相互作用する frontmatter フィールドがいくつかあります。

- **`unlisted: true`** — unlisted のページは、サイドバーから除外されるのと同様に、タグインデックス（`/ja/docs/tags/[tag]` の一覧）やホームページの「All Tags」セクションから除外されます。ただし、ページ自体を URL から直接開いた場合、そのページ下部のタグバッジ列は引き続き表示されます。
- **`draft: true`** — draft のページは本番ビルドから完全に除外されるため、本番環境ではいずれのタグページにも表示されません。

フィールド全体の一覧は [Frontmatter](./frontmatter.mdx#tags) を参照してください。

---

# タグガバナンス

> Source: /pj/zudo-doc/ja/docs/guides/tag-governance

## なぜガバナンスが必要か

最初の10ページほどであれば、自由記述のタグリストで十分です。しかし100ページを超えた頃には、`deployment`、`Deployment`、`deploy`、`deploys`が同じトピックを指しているのに別々のタグとして扱われるようになります。その結果、タグインデックスは役に立たないほぼ重複したエントリで分断され、発見性は向上するどころか悪化します。

タグガバナンスは、プロジェクトのタグセットを`src/config/tag-vocabulary.ts`で定義された**正規ボキャブラリ**に格上げすることでこの問題を解決します。フロントマターで使われるすべてのタグはこのファイルに対して検証されます。タイポやドリフトは監査結果として表面化し、正当な追加はボキャブラリへの意図的な編集となります。

目的は、ドキュメントベースが成長するなかで発見性を鋭く保つことです。緩く始めて、スケールに合わせて締めていきます。

## ボキャブラリファイル

`src/config/tag-vocabulary.ts`は`TagVocabularyEntry`オブジェクトの配列です。各エントリは正規タグ id、任意の表示ラベル、グループ、そしてコンテンツ側で使用を許可するエイリアスを宣言します。

```ts
{
  id: "deployment",
  label: "Deployment",
  description: "Hosting, CI, and release workflows.",
  group: "topic",
  aliases: ["deploy", "deploys"],
}
```

既存ページを壊さずにタグを段階的に廃止するには、deprecated としてマークするか、代替タグへリダイレクトします。エントリを黙って削除してはいけません。フェーズアウト契約の全文は`src/config/tag-vocabulary.ts`のインラインコメントを参照してください。

### プロジェクト側でボキャブラリを拡張する

`create-zudo-doc`でスキャフォールドしたあとは、**`tag-vocabulary.ts`はあなたのプロジェクトのものです。** フレームワーク内部ではなく普通のソースファイルです。フォークやモンキーパッチは不要で、直接編集してください。典型的な追加は次のような形になります。

```ts

  // ...existing entries

  {
    id: "topic:auth",
    label: "Auth",
    description: "Authentication, sessions, SSO.",
    group: "topic",
  },
  {
    id: "type:runbook",
    label: "Runbook",
    description: "Incident response and on-call procedures.",
    group: "type",
  },
];
```

編集後は[`pnpm tags:audit`](./tags-audit.mdx)を実行して想定外の破壊がないか確認し、通常どおりページにタグを付けます。

```mdx
---
title: OAuth 2.0 Setup
tags: [topic:auth, type:runbook]
---
```

## 独立した2つの設定

ガバナンスは`src/config/settings.ts`にある独立した2つの設定で制御します。

| 設定             | 型        | 目的                                                                                                   |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------ |
| `tagVocabulary`  | `boolean` | ボキャブラリファイルを参照するかどうか(エイリアス解決、deprecation、グルーピング)。                    |
| `tagGovernance`  | `"off" \| "warn" \| "strict"` | ボキャブラリが参照される場合の検証レベル。                                                             |

この2つは**直交しています**。`tagVocabulary: false`にすると`tagGovernance`の値に関わらずボキャブラリは完全に無効になります。通常はデフォルトの`tagVocabulary: true`のままにし、`tagGovernance`で強度を調整します。

### 3つのモード

- `"off"` — ボキャブラリを用いた検証を行いません。タグは完全に緩いままです。レガシー移行やプロトタイプで有用です。
- `"warn"`(デフォルト) — `pnpm tags:audit`が未知タグ、deprecation、ニアデュプリケートを報告しますが、`pnpm build`は通過します。修正は自分のペースで進められます。
- `"strict"` — 未知タグは`pnpm check` / `pnpm build`時に Zod バリデーションで落ちます。ボキャブラリが唯一の真実となります。

### 推奨エスカレーションパス

1. **すでに使っているタグからボキャブラリをシードする。** デフォルトのショーケースコンテンツに登場するすべてのタグは`tag-vocabulary.ts`に最初から入っています。
2. **監査がクリーンになるまで`warn`で運用する。** unknown を解消し、`pnpm tags:audit --fix`でエイリアスを書き換え、ニアデュプリケートは正規 id のエイリアスとして吸収します。
3. **監査がグリーンになったら`strict`に切り替える。** 以降、新しいタグには必ずボキャブラリエントリが必要になります——ドリフトを防ぐためにちょうど良い摩擦です。

バックログが空になり次第`strict`を採用してください。制約が入るのは早ければ早いほど安価です。

## ファセットタグのパターン

フラットなタグの海(`deployment`、`advanced`、`tutorial`、`i18n`……)はスケールしません。読者からはタグが何を答えるのかが判別できないからです。ファセットプレフィックスは軸の名前を明示します。

- `type:` — どんな種類のページか? `type:guide`、`type:reference`、`type:tutorial`、`type:runbook`。
- `level:` — 誰向けか? `level:beginner`、`level:advanced`。
- `topic:` — どのテーマを扱うか? `topic:auth`、`topic:ai`、`topic:search`。

デフォルトのボキャブラリは`type:*`と`level:*`のファセットにこのパターンを使っています。独自の`topic:*`エントリを足したり、ドキュメントベースが育ったら新しいファセット(`product:*`、`team:*`)を導入したりできます。ファセットはグループ化されたフッタータグリストで別々に並びます——[フッタータグリスト](./footer-taglist.mdx)を参照してください。

## 次のステップ

- [タグ監査](./tags-audit.mdx) — `pnpm tags:audit`が何を報告し、どう読み解くか。
- [タグサジェスト](./tags-suggest.mdx) — 新しいページ向けのオプトインなローカル LLM サジェスター。
- [フッタータグリスト](./footer-taglist.mdx) — ボキャブラリを読者向けに表示する。

---

# タグ監査

> Source: /pj/zudo-doc/ja/docs/guides/tags-audit

## 監査が報告する内容

`pnpm tags:audit`は`src/content/docs/**`と設定済みのすべてのロケールディレクトリを走査し、各ページのフロントマターから`tags:`配列を収集して、`src/config/tag-vocabulary.ts`と照合した5種類の指摘を報告します。

- **Unknown tags** — 正規 id でもエイリアスでもない文字列です。ボキャブラリエントリを追加するか、ページからタグを削除してください。[`tagGovernance: "strict"`](./tag-governance.mdx)では unknown はビルドを失敗させます。
- **Deprecated tags** — 解決先のエントリが`deprecated`マークされています。エントリに`redirect`があれば読者のトラフィックは代替タグに解決されますが、コンテンツは更新しておくべきです。
- **Alias usage** — 文字列は既知のエイリアスであり、正規 id ではありません。ページは正しくレンダリングされますが、正規形から離れていきます。`--fix`でその場で修正できます。
- **Near-duplicates** — 互いに変種のように見える2つの別個の正規タグ(文字列類似度が高い、または同じ単数形を持つ)。通常はボキャブラリ側の問題で、どちらかを選び、もう一方をエイリアスに回します。
- **Orphan vocabulary entries** — どのページからも参照されていないボキャブラリ id。`deprecated: true`で廃止することを検討してください。

クリーンな実行では`✓ No tag issues found`と表示されます。

## レポートの読み方

デフォルトの出力はカテゴリ別にグループ化された色付きテキストです。機械処理には`--json`を渡します。

```sh
pnpm tags:audit --json > audit.json
```

JSON のペイロードは`AuditReport`で、`unknowns`、`deprecated`、`aliases`、`nearDuplicates`、`orphans`、`filesScanned`、そして正規 id をキーとする`frequency`マップを含みます。CI ダッシュボードや自動修正ツールはこれを消費するべきです。

## `--fix`: バイト安定なエイリアス書き換え

`pnpm tags:audit --fix`は、エイリアスタグをフロントマター内で正規 id に直接書き換えます(1ファイルずつ)。

```sh
pnpm tags:audit --fix
```

知っておくべき挙動:

- **書き換わるのはエイリアスのみ。** unknown・deprecated・ニアデュプリケートは一切触りません——これらは単純な置換ではなく編集判断が必要です。
- **タグブロックの外はバイト安定。** インデントスタイル、クォート、改行コード(LF と CRLF の両方)を含めて他のバイトはすべて保持されます。
- **両方の YAML シーケンススタイルに対応。** フロー形式(`tags: [foo, bar]`)とブロック形式(`tags:\n  - foo`)の両方。

`--fix`は作業ツリーがクリーンな状態で実行し、diff を確認してからコミットしてください。

## `b4push`経由での CI 連携

プロジェクトのプリプッシュ検証スクリプト([`pnpm b4push`](./development-workflow.mdx))は`--ci`付きで監査を実行します。

```sh
pnpm tags:audit --ci
```

`--ci`は`tagGovernance`の設定値に関わらず、**ハード指摘**(unknown または deprecated)があれば非ゼロ終了を強制します。つまり:

- `tagGovernance: "warn"`では——unknown があっても`pnpm build`は通過しますが(マイグレーション中に移行を止めないため意図的)、`pnpm b4push`はプッシュを拒否します。
- `tagGovernance: "strict"`では——ビルドはすでに unknown で落ちます。`--ci`は将来的に enforcement を緩めても b4push が厳しさを保つための安全網です。

この「ビルドは寛容、push は厳格」という2層構造は、複数著者のドキュメントベースの最適解です。ドラフトは Zod と戦わずローカルで試行錯誤できつつ、壊れたタグが`main`に入ることはありません。

## 関連

- [タグガバナンス](./tag-governance.mdx) — ボキャブラリファイル、ガバナンスモード、ファセットパターン。
- [タグサジェスト](./tags-suggest.mdx) — 新しいページで正規タグを選ぶためのオプトイン LLM ヘルパー。

---

# タグサジェスト

> Source: /pj/zudo-doc/ja/docs/guides/tags-suggest

## 自動ではなくオプトイン

`pnpm tags:suggest`は開発者向けのヘルパーであり、ビルドの一部ではありません。1つ以上のドキュメントファイルを読み、ローカルで動いている LLM にプロジェクトボキャブラリから最大3つのタグ id を提案させ、対話プロンプトで表示するか、バッチレビュー用に JSON Lines ファイルへ追記します。

このツールには意図的な3つの選択があります。

- **ローカルモデル、クラウドなし。** プロンプトとドキュメント本文はマシンから出ません。
- **ボキャブラリ対応。** `tag-vocabulary.ts`全体をコンテキストとしてモデルに渡すため、提案は常に正規セットから出てきます。
- **CI では動かさない。** 提案はあくまで参考情報です。`pnpm b4push`、`pnpm build`、プリコミットフックのいずれにも組み込まれていません。

より厳密な強制が欲しい場合は、[`tagGovernance: "strict"`](./tag-governance.mdx)と[`pnpm tags:audit`](./tags-audit.mdx)の役割です。

## Ollama のセットアップ

サジェスターはローカルで動く[Ollama](https://ollama.com/)デーモンと HTTP で通信します。

1. [ollama.com](https://ollama.com/)から Ollama をインストールします。
2. モデルを pull します。

   ```sh
   ollama pull qwen2.5:7b
   ```

3. デーモンが`http://localhost:11434`(デフォルト)で接続できることを確認します。

デフォルトのモデルは`qwen2.5:7b`で、品質・速度・ディスク占有量(約5 GB)のバランスが取れています。`--model`で上書きできます。

```sh
pnpm tags:suggest --model llama3.1:8b src/content/docs/guides/i18n.mdx
```

軽量モデル(`qwen2.5:3b`、`llama3.2:3b`)は高速ですがノイジーです。デーモンに接続できない、あるいは使えない出力が返ってきた場合、ツールは非ゼロ終了します。

## 対話フロー

デフォルト(TTY)フローは1ファイルずつレビューします。

```sh
pnpm tags:suggest src/content/docs/guides/deployment.mdx
```

サジェスターは現在のタグ、LLM の提案した id、そして y/n の確認プロンプトを表示します。受諾するとファイルのフロントマターに書き戻され、拒否すると捨てられます。これが通常の執筆で使うフローです。

## バッチフロー

規模の大きなジョブや非 TTY 環境(CI、エディタプラグイン、パイプした stdin)では`--batch`を渡します。

```sh
pnpm tags:suggest --batch src/content/docs/guides/*.mdx
```

提案はリポジトリルートの`.tag-suggestions.jsonl`へ追記されます——ファイルごとに`file`・`current`・`suggested`を含む JSON オブジェクトが1行です。ドキュメントファイル自体は書き換えられません。JSONL を確認し、良さそうなものを手で適用(あるいはスクリプトで処理)したら、終わったらファイルを削除します。

`--batch`は stdout が TTY でないときにも自動で有効になるため、パイプやリダイレクトでログファイルに流しても意図通りに動きます。

## なぜボキャブラリをコンテキストとして渡すのか

サジェスターを実行するたびに、`tag-vocabulary.ts`全体——id、ラベル、description、group——がプロンプトに含まれます。これが出力品質を決める最大の要因です。

- モデルは正規セットから選ぶため、unknown を除外するラウンドトリップが無駄になりません。
- group と description のコンテキストにより、近いトピック(`content`と`customization`など)を区別できます。
- 新しいボキャブラリエントリを追加することが、ツールに新しいファセットを「教える」主要な手段です——ファインチューニングも埋め込みストアも不要です。

ドキュメント本文はプロンプトを小さく保つために1500文字で切り詰められます。フロントマターに関わる提案材料の大半は最初の1〜2ページに収まるので、この切り詰めが制約になることはほとんどありません。

## 関連

- [タグガバナンス](./tag-governance.mdx) — サジェスターが参照するボキャブラリを定義する。
- [タグ監査](./tags-audit.mdx) — 取りこぼした提案を拾う。

---

# フッタータグリスト

> Source: /pj/zudo-doc/ja/docs/guides/footer-taglist

## 概要

フッタータグリストは、既存のフッターグリッドの中にレンダリングされるタグの索引です。読者は今開いているドキュメントから離れずに、常にすべてのタグページへアクセスできるようになります。

この機能は**デフォルトでオフ**です。`src/config/settings.ts`で`footer.taglist.enabled`を`true`にするまで、フッターの見た目は従来と変わりません。ページごとのタグバッジ行やトップページの"All Tags"セクションも影響を受けません。

## 有効化

既存の`footer`設定に`taglist`ブロックを追加します。

```ts
footer: {
  links: [
    // ...existing footer link columns
  ],
  copyright: `Copyright © ${new Date().getFullYear()} Your Project.`,
  taglist: {
    enabled: true,
    title: "Tags",
    groupBy: "group",
    groupTitles: {
      topic: "By topic",
      type: "By type",
      level: "By level",
    },
    locales: {
      ja: {
        title: "タグ",
        groupTitles: {
          topic: "トピック別",
          type: "種類別",
          level: "レベル別",
        },
      },
    },
  },
},
```

`enabled`以外のフィールドはすべて任意です。省略した項目には妥当なデフォルトが適用されます。

## `groupBy: "group"`と`"flat"`

タグリストは2つのモードでレンダリングできます。

- **`groupBy: "group"`** — ボキャブラリの`group`ごとに1カラム。順序は[`src/config/tag-vocabulary.ts`](./tag-governance.mdx)でその group が最初に登場する順です。ボキャブラリが有効なとき(`tagVocabulary: true`かつ`tagGovernance !== "off"`)のデフォルトです。各カラムのタイトルは`groupTitles[]`から取られ、未指定なら group 名を先頭大文字にしたもの(`topic` → `Topic`)にフォールバックします。
- **`groupBy: "flat"`** — `title`を見出しにした単一のアルファベット順カラム。ボキャブラリが無効のときは強制的にこれになります。タグがほんの少ししかなくグループ表示ではスカスカになる場合にも便利です。

タグが増えてグループ表示で topic と type が実際に分離されるようになったら`"group"`へ切り替えます。それまでは`"flat"`で十分です。

## ロケールオーバーライド

タグリストが表示する文字列はカラムタイトルだけなので、ロケールオーバーライドは小さく保てます。`locales`マップは[設定の`locales`](./configuration.mdx)と同じロケールコードをキーにします。

```ts
taglist: {
  enabled: true,
  title: "Tags",
  groupTitles: { topic: "By topic", type: "By type", level: "By level" },
  locales: {
    ja: {
      title: "タグ",
      groupTitles: { topic: "トピック別", type: "種類別", level: "レベル別" },
    },
  },
},
```

ロケールオブジェクトに存在するキーだけがデフォルトロケールの文字列を上書きし、無いキーはフォールバックします。タグ id そのものは**翻訳されません**——理由は[tags ガイドの i18n セクション](./tags.mdx#i18n-behavior)を参照してください。

## 読者に見える内容

少なくとも1つのドラフトでも unlisted でもないページから参照されているボキャブラリタグは、そのタグのインデックスページ(`/docs/tags//`または`/{locale}/docs/tags//`)へのリンクとして表示されます。deprecated エントリはスキップされます。空のグループは折りたたまれ、埋めたカラムぶんだけ場所を取ります。

## 関連

- [タグガバナンス](./tag-governance.mdx) — タグリストを形作るボキャブラリと group 宣言。
- [タグ](./tags.mdx) — ページごとのタグバッジ行とトップページのタグインデックス。
- [フッター](./footer.mdx) — フッター設定の残りの部分。

---

# Mermaidダイアグラム

> Source: /pj/zudo-doc/ja/docs/components/mermaid-diagrams

`mermaid`言語のフェンスドコードブロックでダイアグラムを描画できます。Mermaidはオンデマンドで読み込まれるため、Mermaidブロックのないページにはオーバーヘッドがありません。

## フローチャート

```mermaid
graph LR
  A[開始] --> B{判定}
  B -->|はい| C[アクション]
  B -->|いいえ| D[別のアクション]
  C --> E[終了]
  D --> E
```

````mdx
```mermaid

graph LR
  A[開始] --> B{判定}
  B -->|はい| C[アクション]
  B -->|いいえ| D[別のアクション]
  C --> E[終了]
  D --> E

```
````

## シーケンス図

```mermaid
sequenceDiagram
  participant ユーザー
  participant アプリ
  participant API
  ユーザー->>アプリ: ボタンクリック
  アプリ->>API: データ取得
  API-->>アプリ: JSONレスポンス
  アプリ-->>ユーザー: 結果表示
```

````mdx
```mermaid

sequenceDiagram
  participant ユーザー
  participant アプリ
  participant API
  ユーザー->>アプリ: ボタンクリック
  アプリ->>API: データ取得
  API-->>アプリ: JSONレスポンス
  アプリ-->>ユーザー: 結果表示

```
````

## 状態遷移図

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Review : 提出
  Review --> Published : 承認
  Review --> Draft : 変更依頼
  Published --> Archived : アーカイブ
  Archived --> [*]
```

````mdx
```mermaid

stateDiagram-v2
  [*] --> Draft
  Draft --> Review : 提出
  Review --> Published : 承認
  Review --> Draft : 変更依頼
  Published --> Archived : アーカイブ
  Archived --> [*]

```
````

## 設定

Mermaidサポートは`src/config/settings.ts`の`mermaid`設定で制御されます：

```ts

  // ...
  mermaid: true, // デフォルトで有効
};
```

サポートされているダイアグラムの種類については、[Mermaid公式ドキュメント](https://mermaid.js.org/)を参照してください。

---

# ドキュメント履歴

> Source: /pj/zudo-doc/ja/docs/guides/doc-history

## 概要

zudo-docは各ドキュメントページのgitリビジョン履歴を表示できます。有効にすると、各詳細ページに**History**ボタンが表示され、過去のリビジョンを閲覧したり、行単位のdiffビューアで任意の2つのバージョンを比較できるサイドパネルが開きます。

これは以下の用途に便利です：

- ドキュメントが時間の経過とともにどのように変化したかを確認する
- リビジョン間で何が変更されたかを理解する
- ドキュメント全体のコンテンツ変更を監査する

この機能はドキュメントがgitリポジトリで管理されている必要があります。履歴は各ファイルに関連するgitコミットから抽出されます。

## ドキュメント履歴の有効化

`src/config/settings.ts`で`docHistory`を`true`に設定します：

```ts

  // ...
  docHistory: true,
};
```

この機能はビルドを高速に保つため、**デフォルトでは無効**です。

## ページごとの表示制御

`docHistory`がグローバルに有効化されたあと、各ページは以下の2つのルールで**History**ボタンを表示するかどうかを決定します。

1. **カテゴリインデックスページの自動抑制** — エントリIDが`/index`で終わるページ（例：`guides/index.mdx`）は、デフォルトでボタンを非表示にします。これらのページは通常ナビゲーションのハブやランディングページであり、リビジョン履歴を表示する意味が薄いためです。
2. **詳細ページはデフォルトで表示** — カテゴリインデックスでない具体的なリーフページはすべてボタンを表示します。

`doc_history`フロントマターフラグでページごとにデフォルトを上書きできます。

```yaml
---
title: My Page
doc_history: false # このページでは常にボタンを非表示
---
```

```yaml
---
title: My Category Index
doc_history: true # インデックスページでも明示的に表示
---
```

フロントマターの指定はどちらの方向にも優先されます。

| ページの種類 | フロントマターなし | `doc_history: true` | `doc_history: false` |
| --- | --- | --- | --- |
| 詳細ページ（リーフ） | 表示 | 表示 | 非表示 |
| カテゴリインデックスページ（`*/index`） | 非表示 | 表示 | 非表示 |

インデックスページにそれなりの分量の本文があり、変更履歴を残す価値がある場合は`doc_history: true`を指定してください。逆に、自動生成された詳細ページや、コミット履歴を表に出したくない詳細ページには`doc_history: false`を指定します。

## 履歴ビューアの使用方法

有効にすると、各詳細ページの本文とフッターの間にある [Body Foot Util エリア](./body-foot-util-area.mdx) の中に **History** ボタンが表示されます。カテゴリインデックスページではデフォルトで非表示です。詳しくは上記[ページごとの表示制御](#ページごとの表示制御)を参照してください。

### リビジョンの閲覧

ボタンをクリックするとリビジョンパネルが開きます。右側からスライドインし、現在のドキュメントを変更したすべてのgitコミットが新しい順に表示されます。各エントリには以下が表示されます：

- **コミットハッシュ**（短縮形）
- コミットの**日付**
- **著者**名
- **コミットメッセージ**（1行目）

### リビジョンの比較

2つのリビジョン間のdiffを表示するには：

1. コミットの横にある**A**ボタンをクリックして**A**（古いリビジョン）を選択
2. 別のコミットの横にある**B**ボタンをクリックして**B**（新しいリビジョン）を選択
3. **Compare**ボタンをクリック

diffビューアは**サイドバイサイド比較**を表示します — 左側に古いリビジョン、右側に新しいリビジョン：

- **緑色の背景** — 新しいリビジョンで追加された行（右側）
- **赤色の背景** — 古いリビジョンから削除された行（左側）
- **灰色のセル** — 一方に対応する行がない空のプレースホルダー
- **変更なしの行** — 両側に表示されるコンテキスト

デフォルトでは、Aは2番目に新しいコミットに、Bは最新のコミットに設定されるため、**Compare**をクリックするだけで最新の変更をすぐに比較できます。

### キーボードショートカット

- **Escape** — 履歴パネルを閉じる
- 別のページに移動するとパネルは自動的に閉じます

## 仕組み

git履歴の抽出はスタンドアロンパッケージ`@zudo-doc/doc-history-server`（`packages/doc-history-server/`に配置）が処理します。このパッケージは開発用と本番ビルド用の2つのモードで動作します。

### ビルドモード

本番環境では、スタンドアロンCLIジェネレーターがすべてのコンテンツファイルをバッチ処理し、JSONの履歴ファイルを`dist/doc-history/`に書き出します。これはAstroサイトビルドと並行した独立したCIジョブとして実行されます：

- **build-site**ジョブ：シャロークローン、`SKIP_DOC_HISTORY=1`でAstroサイトをビルド
- **build-history**ジョブ：フルクローン、`@zudo-doc/doc-history-server generate`を実行
- **deploy**ジョブ：両方のアーティファクトをマージしてデプロイ

この並列戦略により、履歴生成（フルgitクローンを必要とし、すべてのコミットを走査する）がAstroビルドとは独立して実行されるため、合計CIビルド時間が短縮されます。

出力構造はコンテンツディレクトリをミラーします：

```
dist/doc-history/
  getting-started.json
  guides/writing-docs.json
  guides/color.json
  ja/getting-started.json      # ロケールプレフィックス付き
  ja/guides/writing-docs.json
```

### 開発モード

開発モード（`pnpm dev`）では、doc-history-serverがポート4322でスタンドアロンREST APIサーバーとして実行され、`run-p`を使用してAstro開発サーバーと同時に起動されます。Astroインテグレーションがブラウザからの`/doc-history/*`リクエストをこのサーバーにプロキシします。

履歴パネルを開くと、その場でgitコマンドが実行されます -- 事前生成は不要です。サーバーのファイルインデックスは10秒ごとにリフレッシュされるため、新しいファイルやリネームされたファイルが自動的に検出されます。これにより、履歴は最新のコミットと常に同期されます。

`docHistory`を有効にするとビルド時間が増加します。すべてのコンテンツファイルのgit履歴を抽出する必要があるためです。多数のファイルと深い履歴を持つ大規模なドキュメントサイトでは、ビルドに顕著な時間が追加される場合があります。デフォルトの上限はドキュメントあたり**50リビジョン**です。

### 本番出力サイズ

zudo-docはサーバーサイドランタイムなしの完全な静的サイトを生成するため、リクエスト時に`git`コマンドを実行するサーバーがありません。代わりに、ビルドステップですべての履歴データを事前抽出し、`dist/doc-history/`ディレクトリに静的JSONファイルとして出力します。

各JSONファイルには**すべてのリビジョンでの完全なファイル内容**（最大50コミット）が含まれます。これにより、合計出力サイズは以下に比例します：

- ドキュメントファイルの数
- ファイルあたりのgitコミット数
- 各リビジョンでの各ファイルのサイズ

小〜中規模のドキュメントサイトでは通常無視できる程度です。深い履歴を持つ大規模サイトでは、`doc-history/`ディレクトリが大幅に増加する可能性があります。これらのファイルはオンデマンドでのみ取得されるため（ユーザーがHistoryボタンをクリックした時）、初期ページ読み込みには影響しません — ただし、デプロイサイズには追加されます。

デプロイサイズが懸念される場合は、本番ビルドでは`docHistory`を無効（`docHistory: false`）にし、ローカル開発時のみ使用することを検討してください。開発時はdoc-history-server経由で動的に履歴が配信されるため、事前生成コストがかかりません。

## ローカライゼーションサポート

ドキュメント履歴は設定されたすべてのロケールで動作します。各ロケールのコンテンツディレクトリは、ロケールコードがプレフィックスされた独自の履歴ファイルセットを生成します：

- 英語ドキュメント：`/doc-history/{slug}.json`
- 日本語ドキュメント：`/doc-history/ja/{slug}.json`
- ドイツ語ドキュメント：`/doc-history/de/{slug}.json`

履歴パネルは現在のページに基づいて適切なロケール固有の履歴を自動的にリクエストします。

## 技術詳細

### データ形式

各ドキュメントの履歴は以下の構造のJSONファイルとして保存されます：

```ts
interface DocHistoryData {
  slug: string;          // ドキュメントのルートパス
  filePath: string;      // リポジトリ内のファイルパス
  entries: Array<{
    hash: string;        // 完全なコミットハッシュ
    date: string;        // ISO 8601形式の日付
    author: string;      // コミット著者名
    message: string;     // コミットメッセージ（1行目）
    content: string;     // このリビジョンでの完全なファイル内容
  }>;
}
```

### Diffアルゴリズム

diffビューアは[`diff`](https://www.npmjs.com/package/diff)ライブラリの`diffLines`関数を使用して、2つのリビジョン間の行レベルの差分を計算します。GitHubのスプリットdiffビューに似たサイドバイサイドのテーブルレイアウトで表示されます。隣接する削除ブロックと追加ブロックは同じ行にペアリングされるため、何が変更されたかを一目で確認できます。

### リネーム追跡

履歴抽出は`git log --follow`を使用してファイルのリネームを追跡します。ドキュメントが移動またはリネームされた場合、リネーム前のコミットを含む完全な履歴が保持されます。

Historyコンポーネントは`client:idle`で読み込まれるPreactアイランドです。つまり、ページがアイドル状態になってからハイドレーションされます。これにより、初期ページ読み込みパフォーマンスに影響しません。

## doc-history-serverパッケージ

履歴抽出ロジックはAstroビルドパイプライン内ではなく、スタンドアロンパッケージ（`packages/doc-history-server/`）に配置されています。この設計により以下が可能になります：

- **並列CIビルド** -- 履歴生成とサイトビルドが独立したジョブとして実行可能
- **独立した開発** -- サーバーを独立して開発、テスト、バージョニング可能
- **柔軟な使用方法** -- 同一パッケージが開発サーバーとCIジェネレーターの両方を提供

REST APIエンドポイント、CLI引数、データ型、アーキテクチャの詳細については、[Doc History Serverリファレンス](/ja/docs/reference/doc-history-server)を参照してください。

---

# Body Foot Util エリア

> Source: /pj/zudo-doc/ja/docs/guides/body-foot-util-area

すべてのドキュメントページには、本文とフッターの間に小さなユーティリティ帯が配置されます。ここには Document History トリガーと「GitHub でソースを見る」リンクが並び、どちらも `bodyFootUtilArea` という 1 つの設定ブロックで制御します。

History ボタンは以前はフローティング表示でしたが、いまはこのエリアに内包されています。機能自体の説明は [Document History](./doc-history.mdx) を参照してください。

## デフォルト設定

```ts

  // ...
  githubUrl: "https://github.com/zudolab/zudo-doc",
  docHistory: true,
  bodyFootUtilArea: {
    docHistory: true,
    viewSourceLink: true,
  },
};
```

両方のフィールドは既定で `true` です。帯全体を非表示にするにはブロックごと `false` にしてください:

```ts
bodyFootUtilArea: false,
```

## フィールド

| フィールド | 型 | 説明 |
|---|---|---|
| `docHistory` | boolean | 帯の中に Document History トリガーを表示。トップレベルの `docHistory: true` も必要。 |
| `viewSourceLink` | boolean | 「GitHub でソースを見る」リンクを表示。トップレベルの `githubUrl` の設定が必要。 |

表示すべき要素がひとつも無い(たとえば `docHistory: false` かつ `viewSourceLink: false`、あるいは依存フラグが両方オフ)ときは帯そのものが消え、フッターが本文直下に来ます。

## GitHub でソースを見る

`viewSourceLink` が有効かつ `githubUrl` が設定されていると、各ページに対応する `.mdx` へのリンクが表示されます。URL は次のように組み立てられます:

```
${githubUrl}/blob/HEAD/${contentDir}/${entryId}
```

`contentDir` はページが属するコンテンツディレクトリ(英語なら `src/content/docs`、日本語なら `src/content/docs-ja`、バージョンによっては各バージョンの `docsDir`)、`entryId` はその中でのファイルパスです。

| ページ | 解決後の URL |
|---|---|
| `/docs/guides/header-navigation` | `https://github.com/…/blob/HEAD/src/content/docs/guides/header-navigation.mdx` |
| `/ja/docs/guides/header-navigation` | `https://github.com/…/blob/HEAD/src/content/docs-ja/guides/header-navigation.mdx` |

URL は特定ブランチではなく `HEAD` に固定されます。`HEAD` は GitHub 側でリポジトリのデフォルトブランチへ解決されるので、ブランチ名を書かずとも常に最新版へ飛ばせます。

### 日本語ページのフォールバック

日本語ページが英語コンテンツへフォールバックしている場合、リンクは実際に描画された英語ファイル(`src/content/docs/` 側)を指します。

## 片方だけ隠す

不要な項目だけ `false` にしてください:

```ts
// 履歴は出す、ソースリンクは隠す
bodyFootUtilArea: {
  docHistory: true,
  viewSourceLink: false,
},
```

```ts
// 履歴を隠す、ソースリンクは出す
bodyFootUtilArea: {
  docHistory: false,
  viewSourceLink: true,
},
```

ここでの `docHistory` はトップレベルの `docHistory` フラグとは独立しています。トップレベルのフラグは機能全体(ビルド時の履歴生成を含む)の有効化を司り、`bodyFootUtilArea.docHistory` は帯の中にトリガーボタンを置くかどうかだけを決めます。

---

# SiteTreeNav

> Source: /pj/zudo-doc/ja/docs/components/site-tree-nav

## 概要

`SiteTreeNav`は、展開可能なカテゴリカードのレスポンシブグリッドでドキュメントツリー全体を表示するPreactアイランドコンポーネントです。カテゴリの展開・折りたたみが可能な、サイトマップ形式のドキュメントページ一覧を提供します。

このコンポーネントはMDXコンテンツで直接利用することは**できません**。サーバーサイドのデータ取得が必要なため、Astroページテンプレートでインポートする必要があります。以下のライブデモは、グローバルMDXコンポーネントとして登録された`SiteTreeNavDemo`（Astroラッパー）を使用しています。

## ライブデモ

以下は`SiteTreeNav`でドキュメントツリー全体を表示した例です（[ホームページ](/)と同じ表示）：

## 使い方

`SiteTreeNav`は`src/pages/index.astro`でホームページのサイトマップを表示するために使用されています：

```astro
---

const categoryOrder = getCategoryOrder();
const { allDocs, categoryMeta } = await loadLocaleDocs("en");
const navDocs = allDocs.filter((doc) => !doc.data.unlisted);
const tree = buildNavTree(navDocs, "en", categoryMeta);
const groupedTree = groupSatelliteNodes(tree, categoryOrder);
---

```

このコンポーネントは展開・折りたたみのインタラクティブ機能にPreactステートを使用するため、`client:idle`（または他のAstroクライアントディレクティブ）が必要です。

## プロップ

| プロップ | 型 | デフォルト | 説明 |
|------|------|---------|-------------|
| `tree` | `NavNode[]` | （必須） | コンテンツコレクションから構築されたナビゲーションツリー |
| `categoryOrder` | `string[]` | — | トップレベルカテゴリのカスタム並び順 |
| `categoryIgnore` | `string[]` | — | ツリーから非表示にするカテゴリスラッグ |
| `ariaLabel` | `string` | `"Site index"` | nav要素のアクセシビリティラベル |

## 特徴

- **レスポンシブグリッドレイアウト** — `repeat(auto-fill, minmax(min(18rem, 100%), 1fr))`により、モバイルの1カラムからワイドスクリーンの複数カラムまで適応
- **展開可能なカテゴリ** — 各カテゴリカードは折りたたみ可能で、デフォルトでは開いた状態
- **階層的なツリー構造** — ネストされたページはインデントとコネクタラインでツリー構造を表示
- **カテゴリリンク** — トップレベルカテゴリは矢印アイコンとインデックスページへのリンクを表示
- **リーフページ** — 個別のドキュメントページはクリック可能なリンクとして表示

## ソース

コンポーネントは`src/components/site-tree-nav.tsx`に定義されています。

---

# 国際化（i18n）

> Source: /pj/zudo-doc/ja/docs/guides/i18n

zudo-docはAstroの組み込みi18nルーティングを使用して複数の言語をサポートしています。

## 仕組み

- **英語（デフォルト）：** `/docs/...` — コンテンツは`src/content/docs/`に格納
- **日本語：** `/ja/docs/...` — コンテンツは`src/content/docs-ja/`に格納

サイトヘッダーの言語切り替えで、ユーザーは利用可能な言語を切り替えることができます。

## 設定ベースのロケール構成

ロケールは`src/config/settings.ts`で設定します：

```ts

  // ...
  locales: {
    ja: { label: "JA", dir: "src/content/docs-ja" },
  },
};
```

各ロケールエントリに対して、zudo-docは自動的に：

- Astroコンテンツコレクション（`docs-{code}`）を作成
- Astroのi18nルーティングにロケールを登録
- 適切なページルートを生成
- 言語切り替えにロケールを追加

つまり、新しいロケールの追加には設定エントリとコンテンツディレクトリのみが必要です — コレクションやルートの手動セットアップは不要です。

## ディレクトリ構造

ローカライズされたドキュメントは英語のディレクトリ構造をミラーします：

```
src/content/
├── docs/
│   ├── getting-started/
│   │   ├── introduction.mdx
│   │   └── installation.mdx
│   └── guides/
│       └── configuration.mdx
└── docs-ja/
    ├── getting-started/
    │   ├── introduction.mdx
    │   └── installation.mdx
    └── guides/
        └── configuration.mdx
```

## 言語切り替え

言語切り替えはヘッダーの右端に表示されます。現在の言語コード（ENまたはJA）と、別の言語に切り替えるためのリンクが表示されます。切り替えは`/ja/`プレフィックスの追加または削除により、代替URLを自動的に計算します。

## UI翻訳キー

zudo-docは組み込みUI文字列に翻訳キーシステムを使用しています。キーは名前空間ごとに整理されています：

- `nav.*` — ヘッダーナビゲーションラベル（例：`nav.gettingStarted`、`nav.guides`）
- `toc.*` — 目次のラベル
- `search.*` — 検索ダイアログのテキスト
- `code.*` — コードブロックのUI（コピーボタンなど）
- `doc.*` — ドキュメントレベルのUI（編集リンク、メタデータラベルなど）

これらのキーにより、コンテンツだけでなくUI全体をすべての設定済み言語でローカライズできます。

## Astro設定

i18nルーティングは`astro.config.ts`で設定されます：

```ts
i18n: {
  defaultLocale: "en",
  locales: ["en", ...Object.keys(settings.locales)],
  routing: {
    prefixDefaultLocale: false,
  },
},
```

`prefixDefaultLocale: false`により、英語ページは言語プレフィックスなし（`/docs/...`）で配信され、日本語ページは`/ja/`プレフィックス付き（`/ja/docs/...`）で配信されます。

`astro.config.ts`の`locales`配列は`settings.locales`から自動的に導出されるため、ロケールの管理は一箇所のみで行えます。

## 新しい言語の追加

新しい言語（例：韓国語）を追加するには：

1. `settings.ts`にロケールを追加：

   ```ts
   locales: {
     ja: { label: "JA", dir: "src/content/docs-ja" },
     ko: { label: "KO", dir: "src/content/docs-ko" },
   },
   ```

2. コンテンツディレクトリを作成：`src/content/docs-ko/`
3. 英語のディレクトリ構造をミラーして翻訳ファイルを配置
4. `src/pages/ko/docs/[...slug].astro`に新しいページルートを追加（既存のロケールルートからコピー）
5. 新しいロケール用のUI翻訳を追加

ステップ1が最も重要です — `settings.ts`にロケールを追加すると、コンテンツコレクションの作成とi18nルーティングの登録が自動的に行われます。残りのステップはコンテンツとページルートを提供します。

---

# フロントマタープレビュー

> Source: /pj/zudo-doc/ja/docs/reference/frontmatter-preview

フロントマタープレビューブロックは、ドキュメントに無視されていないフロントマターキーが含まれている場合、ページタイトルの下に自動的に表示されます。カスタムフィールドをコンパクトなキー/値テーブルとしてレンダリングし、著者情報、ステータス、バージョンなどのドキュメントメタデータを本文中に埋め込まずに表示するのに便利です。

このページ自体がその機能のデモです。上部に表示されている `author` と `status` フィールドは、このページ自身のフロントマターで宣言されています。

## ブロックが表示される条件

フィルタリングを経て少なくとも1つのフロントマターキーが残った場合のみブロックが表示されます。フレームワーク管理のキー（`title`、`description`、`sidebar_position`、`tags` など）はデフォルトで除外されます。すべてのキーが無視リストに含まれている場合は何も表示されません。

`src/config/settings.ts` で `frontmatterPreview: false` を設定すると、すべてのページでこの機能を無効にできます。

## デフォルト無視リスト

以下のキーはデフォルトで無視されます。これらはコンテンツスキームで定義されたすべてのフィールドに対応しており、再表示しても冗長になるだけです。

| キー | 理由 |
|-----|------|
| `title` | ページの `h1` としてレンダリング |
| `description` | タイトルの下にサブタイトルとして表示 |
| `sidebar_position` | ナビゲーション内部メタデータ |
| `sidebar_label` | ナビゲーション内部メタデータ |
| `category` | ナビゲーション内部メタデータ |
| `tags` | タグバッジとして別途レンダリング |
| `search_exclude` | ビルド時フラグ |
| `pagination_next` | ビルド時フラグ |
| `pagination_prev` | ビルド時フラグ |
| `draft` | ビルド時フラグ |
| `unlisted` | ビルド時フラグ |
| `hide_sidebar` | レイアウトフラグ |
| `hide_toc` | レイアウトフラグ |
| `standalone` | レイアウトフラグ |
| `slug` | URL オーバーライド |
| `generated` | ビルド時フラグ |

このリストにないキーは自動的に表示されます。

## 無視リストのカスタマイズ

`src/config/settings.ts` の `frontmatterPreview` 設定には、互いに排他的な2つの設定があります。

### `extraIgnoreKeys` — デフォルトを拡張する

デフォルト設定を破棄せずにキーを無視リストに追加します。プロジェクト全体で非表示にしたいカスタムフロントマターフィールドがある場合に使用します。

```ts
frontmatterPreview: {
  extraIgnoreKeys: ["reviewed_by", "internal_id"],
},
```

### `ignoreKeys` — デフォルトを置き換える

組み込みの無視リストを完全に置き換えます。非表示にするキーを完全に制御したい場合に使用します。`ignoreKeys` が存在する場合、`extraIgnoreKeys` は無視されます。

```ts
frontmatterPreview: {
  ignoreKeys: ["title", "description", "sidebar_position"],
},
```

`ignoreKeys` を使用する際に標準スキーマキーを含めないと、`draft` や `unlisted` などのフレームワーク内部フィールドがテーブルに表示される可能性があります。ほとんどの場合、`extraIgnoreKeys` を使用する方が安全です。

## 機能を無効にする

`frontmatterPreview: false` を設定すると、すべてのページからブロックを一括削除できます。

```ts
frontmatterPreview: false,
```

## 使用例

次のフロントマターは `author` と `status` が表示されるプレビューテーブルを生成します。`title`、`description`、`sidebar_position` はフィルタリングされます。

```mdx
---
title: My Release Notes
description: What changed in v2.
sidebar_position: 5
author: Jane Doe
status: released
---
```

レンダリングされたテーブル：

| キー | 値 |
|-----|---|
| `author` | Jane Doe |
| `status` | released |

完全な設定リファレンスについては、[設定 — frontmatterPreview](../guides/configuration.mdx#frontmatterpreview) を参照してください。

## カスタムレンダラー

デフォルトでは、フロントマターの値はプレーンテキストとしてレンダリングされます。値をスタイル付きコンポーネント（カラーピル、リンク、アイコンなど）に置き換えるには、`src/config/frontmatter-preview-renderers.tsx` にカスタムレンダラーを登録します。

### コンポーネントの型

各レンダラーは `FrontmatterRendererProps` を受け取る Preact コンポーネントです：

| プロップ | 型 | 説明 |
|------|------|-------------|
| `value` | `NonNullable` | フロントマターの値（null/undefined は渡されません） |
| `entryKey` | `string` | フロントマターのキー名 |
| `data` | `Record` | 現在のページのフロントマター全体 |
| `locale` | `Locale \| undefined` | アクティブなロケール |

### レンダラーの登録

`src/config/frontmatter-preview-renderers.tsx` を開き、エクスポートされた `frontmatterRenderers` マップにキーを追加します。各値は `FrontmatterRendererProps` を受け取り、JSX または `null` を返すコンポーネント関数です：

```tsx
discount: ({ value }) => {
  if (value !== true) return null;
  return (
    
      ON SALE
    
  );
},
```

このページのフロントマターには `discount: true`、`status: "stable"`、`difficulty: "beginner"` が含まれており、ページ上部のメタデータテーブルにカラーピルとして表示されています。

### 無視リストの優先順位

無視リストに登録されているキーのレンダラーは効果がありません。無視リストはレンダラーの検索より _前_ に適用されます。キーが抑制されている場合、行はレンダリングされず、レンダラーも呼び出されません。

フレームワーク管理のキー（`draft` など）をカスタムレンダラーで表示するには、まず `src/config/settings.ts` の無視リストからそのキーを削除してください：

```ts
frontmatterPreview: {
  // 非表示にするすべてのキーを明示的に列挙 — ignoreKeys はデフォルトを置き換えます
  ignoreKeys: ["title", "description", "sidebar_position", "tags"],
},
```

`ignoreKeys` はデフォルトの無視リスト全体を置き換えます。`tags`、`slug`、`unlisted` などの標準スキーマキーを省略すると、それらがプレビューテーブルに表示されます。ほとんどの場合、デフォルトを拡張する `extraIgnoreKeys` の使用を推奨します。

レンダラーはプロジェクトの `src/config/frontmatter-preview-renderers.tsx` に登録します。デフォルトでは空のマップが用意されています。

---

# CategoryNav

> Source: /pj/zudo-doc/ja/docs/components/category-nav

## 概要

`CategoryNav`は、カテゴリの子ページをカードグリッドとして自動的に一覧表示するAstroコンポーネントです。カテゴリの`index.mdx`ファイルで使用し、すべての子ページへのリンクを含むランディングページを作成するために設計されています。

`CategoryNav`はすべてのMDXドキュメントページでグローバルに利用できます — インポートは不要です。アドモニションコンポーネント（`Note`、`Tip`など）と同様に、ドキュメントページルートで登録されています。

## ライブデモ

以下は`CategoryNav`で「はじめに」カテゴリを表示した例です：

## 使い方

カテゴリの`index.mdx`で`CategoryNav`を使用してランディングページを作成します：

```mdx
---
title: Getting Started
sidebar_position: 0
---

Welcome to the Getting Started section. Choose a topic below to begin.

```

`CategoryNav`はAstroコンポーネント（クライアントサイドJavaScriptなし）のため、`client:`ディレクティブは不要です。

## プロップ

| プロップ | 型 | デフォルト | 説明 |
|------|------|---------|-------------|
| `category` | `string` | （必須） | カテゴリスラッグ（例：`"guides"`、`"reference"`） |
| `lang` | `Locale` | 自動検出 | コンテンツコレクションのロケールを上書き |

`lang`プロップは現在のURLパスから自動的に検出されるため、通常は設定する必要はありません。

## 特徴

- **2カラムグリッド** — デスクトップでは`sm:grid-cols-2`、モバイルではシングルカラムで表示
- **カード表示** — 各カードにはページタイトル（リンク付き）とdescription（frontmatterから取得）を表示
- **ホバーエフェクト** — ホバー時にカードのボーダーがハイライトされ、タイトルリンクは常に下線付き
- **インデックス自動除外** — カテゴリ自身のインデックスページは自動的にフィルタリング
- **ポジション順ソート** — カードはfrontmatterの`sidebar_position`順に並びます

## 使用場所

任意のカテゴリの`index.mdx`に`CategoryNav`を追加してランディングページを生成できます。例えば、「はじめに」セクションでは以下のように使用されています：

```
src/content/docs/
  getting-started/
    index.mdx              ←  を使用
    introduction.mdx
    installation.mdx
    writing-docs.mdx
```

## ソース

コンポーネントは`src/components/category-nav.astro`に定義されています。

---

# Claude Codeリソース

> Source: /pj/zudo-doc/ja/docs/guides/claude-resources

## 概要

zudo-docはプロジェクトのClaude Codeリソース — CLAUDE.mdファイル、カスタムコマンド、スキル、エージェント — からドキュメントページを自動的に生成できます。有効にすると、これらは**Claude**ヘッダーナビゲーションセクションに表示されます。

## Claude Resourcesの有効化

`src/config/settings.ts`で`claudeResources`を設定します：

```ts
claudeResources: {
  claudeDir: ".claude",
},
```

無効にするには`false`に設定します：

```ts
claudeResources: false,
```

## 生成されるもの

インテグレーションは`.claude/`ディレクトリをスキャンし、以下のMDXドキュメントページを生成します：

| リソース | ソース | 出力 |
|----------|--------|--------|
| CLAUDE.mdファイル | プロジェクトルートとサブディレクトリ | `claude-md/` |
| コマンド | `.claude/commands/*.md` | `claude-commands/` |
| スキル | `.claude/skills/*/SKILL.md` | `claude-skills/` |
| エージェント | `.claude/agents/*.md` | `claude-agents/` |

各リソースタイプには、すべてのアイテムのリストを含むインデックスページと個別の詳細ページが用意されます。

## 仕組み

インテグレーションはビルド時に`astro:config:setup`フックで実行されます：

1. 設定された`.claude/`ディレクトリをスキャン
2. CLAUDE.mdファイル、コマンド、スキル（リファレンス付き）、エージェントを検出
3. `src/content/docs/claude-*/`ディレクトリにMDXファイルを生成
4. これらのファイルはAstroのコンテンツコレクションによって取得され、ドキュメントページとしてレンダリング

生成されたページは**Claude**ヘッダーナビゲーションタブに表示されます。`headerNav`で`categoryMatch: "claude"`を設定して構成します。

生成されたファイルは`src/content/docs/`に書き込まれ、ビルドごとに再作成されます。手動で編集しないでください — 変更は上書きされます。

## 設定オプション

| オプション | 型 | 説明 |
|--------|------|-------------|
| `claudeDir` | string | `.claude/`ディレクトリへのパス（プロジェクトルートからの相対パス） |
| `projectRoot` | string | CLAUDE.mdファイルパスの解決に使用するオプションのプロジェクトルートオーバーライド |

`projectRoot`オプションは、`.claude/`ディレクトリがプロジェクトルートにないモノレポ設定で便利です。

`references/`サブディレクトリを持つスキルは、そのリファレンスドキュメントが個別のリンクされたページとして含まれるため、バンドルされたナレッジベースを簡単に閲覧できます。

---

# llms.txt

> Source: /pj/zudo-doc/ja/docs/guides/llms-txt

zudo-docは`llms.txt`と`llms-full.txt`ファイルを自動生成し、AIツールや大規模言語モデルがドキュメントを容易に利用できるようにします。

[llms.txt標準](https://llmstxt.org/)は、AIツールがドキュメントを発見・読み取りやすくするための新しい規約です。多くのAIツールがすでにこれらのファイルを参照しています。

## 仕組み

有効にすると、zudo-docはビルド時に2つのファイルを生成します：

- **`/llms.txt`** — すべてのドキュメントページのタイトル、説明、URLを一覧にしたインデックス
- **`/llms-full.txt`** — すべてのドキュメントページの全文を1つのファイルにまとめたもの

これらのファイルは、AIツールがHTMLを解析せずに利用できる機械可読形式のドキュメントを提供します。

## llms.txtの有効化

この機能は**デフォルトで有効**です。明示的に制御するには、`src/config/settings.ts`で`llmsTxt`を設定します：

```ts

  // ...
  llmsTxt: true,  // デフォルトで有効
};
```

無効にするには：

```ts
llmsTxt: false,
```

## 生成される出力

### llms.txt（インデックス）

インデックスファイルは、各ドキュメントページのタイトル、説明、URLを一覧表示します：

```
# My Documentation

> Site description from settings

## Docs

- [Introduction](/docs/getting-started/introduction): Learn what the project is and how it works.
- [Configuration](/docs/guides/configuration): Global settings and configuration reference.
```

### llms-full.txt（全文）

全文ファイルは、すべてのドキュメントページの完全なテキストを見出しで区切って含みます：

```
# My Documentation

> Site description from settings

## Introduction

Welcome to the project...

## Configuration

The project is configured through...
```

## ページの除外

以下のフロントマターフィールドを持つページは、両方の生成ファイルから自動的に除外されます：

- `draft: true` — ビルドから除外される下書きページ
- `unlisted: true` — ビルドされるが非表示のページ
- `search_exclude: true` — 検索から除外されるページ

```mdx
---
title: Internal Notes
search_exclude: true
---
```

## マルチロケール対応

ロケールが設定されている場合、zudo-docは各ロケールごとに個別のllms.txtファイルを生成します：

- **英語（デフォルト）：** `/llms.txt`と`/llms-full.txt`
- **日本語：** `/ja/llms.txt`と`/ja/llms-full.txt`

各ロケールのファイルには、そのロケールのコンテンツディレクトリのページのみが含まれます。各ファイル内のURLには適切なロケールプレフィックスが使用されます。

## HTMLによる検出

`llmsTxt`が有効な場合、zudo-docはすべてのページの``に``タグを追加し、サイトがサブパスにデプロイされている場合でもAIツールがファイルを発見できるようにします：

```html

```

これは、サイトが`/pj/zudo-doc/`のような`base`パスを使用している場合に機能しない可能性がある、標準的なパスベースの検出（ドメインルートの`/llms.txt`）を補完します。

## 開発モード

生成されるファイルはViteミドルウェア経由で開発中も利用可能です。`pnpm dev`実行時、`/llms.txt`と`/llms-full.txt`へのリクエストは動的に処理されます — ビルドステップは不要です。

テストのためにビルドする必要はありません。llms.txtファイルは検索と同様に`pnpm dev`ですぐに動作します。

## 本番ビルド

`pnpm build`時、ファイルはサイトの他の部分とともに`dist/`ディレクトリに静的テキストファイルとして出力されます。

---

# Design Token Panel

> Source: /pj/zudo-doc/ja/docs/reference/design-token-panel

Design Token Panelは、テーマが提供するすべてのデザイントークンをページ上で編集できるインタラクティブなエディタです。以前のColor Tweak Panel（カラー専用）を置き換え、**Spacing**・**Font**・**Size**・**Color**の4つのトークン種別をタブ構成でカバーします。さらに統一されたJSONエクスポート／インポート機能を備えており、デザインをまとめてAIアシスタントに渡し、返ってきた結果を読み込むラウンドトリップ運用が可能です。

## パネルを有効にする

`src/config/settings.ts` で `designTokenPanel` を `true` に設定します:

```ts title="src/config/settings.ts"

  designTokenPanel: true,
  // ...
};
```

有効になると、ヘッダーに（検索アイコンの左側に）パレットアイコンが表示されます。クリックするとパネルが開閉し、以前のColor Tweak Panelと同じキーボードショートカットも引き続き利用できます。

`designTokenPanel` は従来の `colorTweakPanel` 設定を置き換えます。既存プロジェクトの互換性のため、`colorTweakPanel` は1リリースのあいだエイリアスとして受け付けます — どちらかが `true` であればパネルは有効になります。新規プロジェクトでは `designTokenPanel` を使ってください。

## 4つのタブ

パネルは4つのタブに分かれており、それぞれ単一のトークン種別に集中しています。各タブには担当するトークン以外は表示されないため、色の下までスクロールしてスペーシングにたどり着く必要はありません。

### Spacing

水平（`hsp-*`）と垂直（`vsp-*`）のスペーシングスケールを編集するスライダーです。`3xs` から `2xl` までの各ステップに対応するスライダーがあり、ドラッグに応じて縮んだり伸びたりするライブプレビューを表示します。値はレイアウトが潰れないよう、妥当な最小値にクランプされます。

### Font

タイポグラフィスケール用のコントロール:

- フォントファミリー選択（プリセットまたはカスタム）
- 数値テキスト入力による抽象スケールトークン（`2xs` → `2xl`）。CSS値のサニタイズあり
- セマンティックロール（`caption`・`body`・`heading` など）のマッピング設定

フォントファミリー入力は、複数スタックのフォールバックを含む任意の有効な `font-family` 値を受け付けます。無効な値（引用符の不一致、生のJavaScriptなど）は入力確定時に拒否されるため、貼り付けたスニペットによってページが壊れることはありません。

### Size

セマンティックなアイコンサイズトークン（`icon-xs` → `icon-lg`）や、任意値からセマンティックトークンに昇格したコンポーネント寸法に対応する、ピル型スライダーです。各スライダーは、2階層サイズ戦略で想定されるpx値にスナップします。

### Color

Colorタブは、以前のColor Tweak Panelがタブの1つに収まった形です。以下を含みます:

- 16色パレット（`p0`〜`p15`）
- ベーステーマカラー（`bg`・`fg`・`cursor`・`sel-bg`・`sel-fg`）
- セマンティックトークンの上書き（`accent`・`code-bg`・`success`・`danger` など）
- 50種類以上のバンドル済みプリセットから読み込める **Scheme…** ドロップダウン

#### マッチキーワード用トークン

検索結果でマッチしたキーワードのハイライト色を制御する2つのセマンティックカラートークンがあります。Colorタブの他のセマンティック上書きと並んで配置され、`src/components/search.astro` が検索UIのヒット箇所のスタイリングで参照します。

- `matchedKeywordBg` — マッチしたキーワードの背景に塗られる色。
- `matchedKeywordFg` — その背景の上に重なる、マッチしたキーワードの文字色。

## キーボードアクセシビリティ

タブの切り替えは標準的なWAI-ARIA Tabsパターンを実装しています:

| キー | 動作 |
|---|---|
| `←` / `→` | 前／次のタブにフォーカスを移動 |
| `Home` | 最初のタブにフォーカス |
| `End` | 最後のタブにフォーカス |
| `Enter` / `Space` | フォーカス中のタブをアクティブ化 |

タブは自動アクティブ化方式で、矢印キーでフォーカスを移動するとパネルの表示も切り替わります。各タブ内のすべてのスライダー・セレクト・テキスト入力は `Tab` で辿れ、すべてのコントロールに可視のフォーカスリングが用意されています。

## JSONエクスポート — 既定では差分のみ

パネルヘッダーの **Export** をクリックすると、エクスポートモーダルが開きます。モーダルには、各タブの現在の状態を表す単一のJSONドキュメントが表示されます。

既定のエクスポートは**デフォルトとの差分**です — 実際に変更したトークンだけが含まれます。まったく触っていないトークン種別は丸ごと省略され、変更があった種別のなかでも編集したトークンだけが残ります。差分は小さく、diffしやすく、コミットに貼り付けても安定した出力になります。

```json
{
  "version": 2,
  "spacing": {
    "hsp": { "md": "1.25rem" }
  },
  "color": {
    "palette": {
      "6": "#7aa2f7"
    },
    "semanticMappings": {
      "accent": 6
    }
  }
}
```

モーダルヘッダーの **Show defaults too** トグルを有効にすると、未変更のデフォルトを含む完全なトークンツリーを出力できます。テーマの全容を知らないデザイナーやAIに渡すスナップショットが必要な場合は、この形式を使ってください。

## JSONから読み込み

**Load…** ボタンを押すとインポートモーダルが開きます。以前のエクスポートやAIが生成したJSONドキュメントを貼り付けると、パネルは次の処理を行います:

1. 形状を検証（バージョン・既知のキー・値の妥当性）。
2. 不明なキーや不正な値を致命的でない警告として報告。
3. ドキュメントを現在のデフォルトにマージ。未指定のトークンはデフォルトのまま、明示されたトークンだけが上書きされます。
4. 結果を `localStorage` に永続化し、すべてのCSSカスタムプロパティを即時に再適用。

不正なJSONは具体的なエラーメッセージとともに拒否されます。`spacing.hsp.md` だけを変更するような部分的なインポートも、正規のユースケースとしてサポートされます。

## AIワークフロー

差分のみのエクスポートとJSONロードを組み合わせると、チャット型AIとの単純なラウンドトリップが実現できます:

1. 渡したいトークンを**編集**（触らなくてもOK）。
2. 差分を**エクスポート**してJSONをコピー。
3. AIチャットに**貼り付け**、自然言語でリクエストを添える。例:

   > これは現在のデザイントークンの差分です。カラーパレットはそのままに、より温かみがあり、コントラストの強いタイポグラフィスケールに書き換え、JSONだけを返してください。

4. AIが返したJSONを **Load…** に**貼り付け**。
5. パネルが検証・マージ・反映を即座に行います。結果が気に入らなければ、ヘッダーの **Reset all** で巻き戻せます。

既定のエクスポートが差分になっているため、AIは気にしているトークンだけを読むことになり、未変更のデフォルトを推理する必要がありません。AIに全体像が必要な場合（例: ゼロから新しいテーマを作らせるとき）にだけ **Show defaults too** をオンにしてください。

## 永続化とマイグレーション

状態は `localStorage` のキー `zudo-doc-tweak-state-v2` に永続化されます。v2形式は各タブの状態を横並びにした単一オブジェクトなので、1回の読み込みでパネル全体が復元されます。

以前のプロジェクトで `zudo-doc-tweak-state` の下に保存されていたv1（カラーのみ）の状態は、自動的にマイグレーションされます:

- パネルは読み込み時にまずv2を参照します。v2が無ければ、v1の状態（カラートークンのみ）を解釈し、v2のColorタブへ昇格させます。
- `doc-layout.astro` が `` に注入するFOUC防止スクリプトも、v2→v1の同じ順で参照します。これにより、古いデバイスでも最初のペイント前に保存済みのカラーが適用されます。
- ヘッダーの **Reset all** をクリックすると両方のキーがクリアされ、`src/config/settings.ts` で宣言されたカラースキームに戻ります。

## 設定リファレンス

| 設定 | 型 | 説明 |
|---|---|---|
| `designTokenPanel` | `boolean` | パネルを有効にします。デフォルトは `false`。 |
| `colorTweakPanel` | `boolean \| undefined` | `designTokenPanel` の**非推奨**エイリアス。いずれかが truthy のときパネルは有効になります。将来のリリースで削除される予定です。 |

トークンそのもの（スペーシングスケール・フォントスケール・アイコンサイズ・パレット）は、引き続き `src/styles/global.css` の `@theme` と `src/config/color-schemes.ts` で設定します。パネルはブラウザ内のコピーを編集するだけで、ソースファイルに書き戻すことはありません。

気に入った組み合わせが見つかったら、差分をエクスポートしてコミットメッセージやデザインドキュメントに貼り付けてみてください — いま行った変更を再現するもっとも小さな説明になります。

---

# CategoryTreeNav

> Source: /pj/zudo-doc/ja/docs/components/category-tree-nav

## 概要

`CategoryTreeNav`は、カテゴリの子ページをネストされたツリー形式のリンク（`ul > li > ul > li`パターン）で表示するAstroコンポーネントです。カードグリッドスタイルの`CategoryNav`の代替として、より深いネストを持つカテゴリに適したコンパクトな表示を提供します。

`CategoryTreeNav`はすべてのMDXドキュメントページでグローバルに利用できます — インポートは不要です。アドモニションコンポーネント（`Note`、`Tip`など）と同様に、ドキュメントページルートで登録されています。

## ライブデモ

以下は`CategoryTreeNav`で「ガイド」カテゴリを表示した例です：

## 使い方

カテゴリの`index.mdx`で`CategoryTreeNav`を使用してコンパクトなツリー形式のリストを作成します：

```mdx
---
title: Getting Started
sidebar_position: 0
---

Welcome to the Getting Started section.

```

`CategoryTreeNav`はAstroコンポーネント（クライアントサイドJavaScriptなし）のため、`client:`ディレクティブは不要です。

## CategoryNavとの比較

| 特徴 | CategoryNav | CategoryTreeNav |
|---------|-------------|-----------------|
| レイアウト | 2カラムカードグリッド | ネストされたツリーリスト |
| 説明文 | 各カード内に表示 | タイトルの後にインラインで表示 |
| ネスト | フラット（子のみ） | 最大3階層まで |
| 最適な用途 | ランディングページ、概要 | 深い階層構造、コンパクトな一覧 |

## プロップ

| プロップ | 型 | デフォルト | 説明 |
|------|------|---------|-------------|
| `category` | `string` | （必須） | カテゴリスラッグ（例：`"guides"`、`"reference"`） |
| `lang` | `Locale` | 自動検出 | コンテンツコレクションのロケールを上書き |

`lang`プロップは現在のURLパスから自動的に検出されるため、通常は設定する必要はありません。

## ソース

コンポーネントは`src/components/category-tree-nav.astro`に定義されています。

---

# HtmlPreview

> Source: /pj/zudo-doc/ja/docs/components/html-preview

`` は、分離された iframe 内で HTML/CSS のライブデモを描画するコンポーネントです。ビューポートプリセット（Mobile / Tablet / Full）とシンタックスハイライト付きの折りたたみ可能なソースコードパネルを備えています。すべての MDX ファイルでインポートなしで使用できます。

## 基本的な使い方

Hello, world!
  `}
  css={`
    .box {
      padding: 24px;
      background: #3b82f6;
      color: #fff;
      border-radius: 8px;
      font-family: system-ui, sans-serif;
      text-align: center;
    }
  `}
/>

````mdx
Hello, world!
  `}
  css={`
    .box {
      padding: 24px;
      background: #3b82f6;
      color: #fff;
      border-radius: 8px;
      font-family: system-ui, sans-serif;
      text-align: center;
    }
  `}
/>
````

## レスポンシブレイアウト

ビューポートボタン（Mobile / Tablet / Full）を使って、異なる幅でコンテンツがどのように変化するかを確認できます。プレビュー領域の右下にあるドラッグハンドルでリサイズすることもできます。

      Card 1
      Card 2
      Card 3
      Card 4
    
  `}
  css={`
    .grid {
      display: grid;
      grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
      gap: 12px;
      padding: 16px;
      font-family: system-ui, sans-serif;
    }
    .card {
      padding: 20px;
      background: #f1f5f9;
      border: 1px solid #e2e8f0;
      border-radius: 6px;
      text-align: center;
      color: #334155;
    }
  `}
/>

## HTML のみ

`css` プロップを指定しない場合は、HTML のソースのみが表示されます。

      1つ目の項目
      2つ目の項目
      3つ目の項目
    
  `}
/>

## デフォルトでコードを表示

`defaultOpen` を指定すると、ソースコードが最初から展開された状態で表示されます。

Click me
  `}
  css={`
    .btn {
      padding: 10px 20px;
      background: #8b5cf6;
      color: #fff;
      border: none;
      border-radius: 6px;
      font-size: 14px;
      font-family: system-ui, sans-serif;
      cursor: pointer;
    }
    .btn:hover {
      background: #7c3aed;
    }
  `}
/>

## 固定高さ

`height` プロップを使って、自動調整の代わりに iframe の高さを固定できます。

      このプレビューは300pxの固定高さです。
      高さを超えるコンテンツは iframe 内でスクロールします。
    
  `}
  css={`
    .scroll-content {
      padding: 16px;
      font-family: system-ui, sans-serif;
      color: #334155;
      line-height: 1.6;
    }
  `}
/>

## 外部リソース

CSS フレームワーク、Web フォント、スクリプトなどの外部リソースをプレビューに読み込めます。`settings.ts` でグローバルに設定するか、コンポーネントのプロップで個別に指定します。

### グローバル設定

`src/config/settings.ts` で `htmlPreview` を設定すると、すべてのプレビューにリソースが適用されます：

```ts
htmlPreview: {
  head: ``,
  css: `body { font-family: 'Noto Sans JP', sans-serif; }`,
  js: `console.log('preview loaded');`,
}
```

### コンポーネント単位のプロップ

`head` と `js` プロップを使って、個別のプレビューにリソースを追加できます。グローバル設定の後にマージされます。

待機中...
  `}
  css={`
    #output {
      padding: 16px;
      font-family: system-ui, sans-serif;
      color: #334155;
    }
  `}
  js={`
    document.getElementById('output').textContent = 'JS から Hello!';
  `}
/>

````mdx
待機中...
  `}
  css={`
    #output {
      padding: 16px;
      font-family: system-ui, sans-serif;
      color: #334155;
    }
  `}
  js={`
    document.getElementById('output').textContent = 'JS から Hello!';
  `}
/>
````

## Props

| プロップ | 型 | デフォルト | 説明 |
|------|------|---------|-------------|
| `html` | string | （必須） | プレビュー iframe 内に描画する HTML コンテンツ |
| `css` | string | `undefined` | プレビュー iframe 内に適用する CSS スタイル |
| `head` | string | `undefined` | `` に挿入する生の HTML（リンク、メタ、フォント） |
| `js` | string | `undefined` | プレビュー iframe 内で実行する JavaScript |
| `title` | string | `undefined` | プレビューヘッダーバーに表示するタイトル |
| `height` | number | auto | iframe の固定高さ（ピクセル）。省略時はコンテンツに合わせて自動調整 |
| `defaultOpen` | boolean | `false` | ソースコードパネルをデフォルトで展開表示する |

## サポートされている言語

ソースコードパネルは軽量な Shiki インスタンスを使用しており、以下の言語に対応しています：

- `html` — HTML パネルおよび Head パネル
- `css` — CSS パネル
- `javascript` — JS パネル

サポートされていない言語はプレーンテキスト（ハイライトなし）にフォールバックします。これは標準のコードブロックで利用可能な[言語一覧](/ja/docs/components/basic-components#サポートされている言語)より小さなサブセットです。

## 注意事項

- プレビューは CSS リセット（Tailwind v4 preflight）を含む分離された `` 内で描画されるため、スタイルが外部に漏れることはありません。
- プレビューは `sandbox` 属性なしで動作します。`srcdoc` の内容は作成者が管理する MDX であるため、追加の分離は不要です。
- `settings.htmlPreview` のグローバルリソースは、コンポーネント単位のプロップの前に挿入されます。
- `html`、`css`、`js` プロップはインデント付きのテンプレートリテラルに対応しています。先頭の空白はソースコード表示時に自動的に除去されます。
- クライアントサイドのハイドレーションはコンポーネントラッパーにより自動的に処理されるため、MDX 内で `client:load` ディレクティブを付ける必要はありません。

---

# ドキュメントスキルシムリンカー

> Source: /pj/zudo-doc/ja/docs/guides/doc-skill-symlinker

## 概要

**ドキュメントスキルシムリンカー**は、ドキュメントコンテンツから[Claude Codeスキル](https://docs.anthropic.com/en/docs/claude-code/skills)を作成します。セットアップ後、任意のClaude Codeセッション内でスキルを呼び出してドキュメントを参照できます。

## セットアップ

セットアップスクリプトを実行します:

```bash
pnpm run setup:doc-skill
```

スキル名の入力を求められます。デフォルトは `<プロジェクト名>-wisdom`（例: `zudo-doc-wisdom`）です。

## 使い方

セットアップ後、任意のClaude Codeセッションでスキルを使用できます:

```
/zudo-doc-wisdom sidebar
```

Claudeが関連するドキュメント記事を検索し、回答に利用します。スキルはグローバルにシムリンクされているため、どのプロジェクトディレクトリからでも動作します。

## 作成されるファイル

セットアップスクリプトを実行すると、以下のファイルが作成されます:

```
.claude/skills//
├── SKILL.md       # スキル定義（フロントマターと指示）
├── docs -> src/content/docs/         # 英語ドキュメントへのシムリンク
└── docs-ja -> src/content/docs-ja/   # 日本語ドキュメントへのシムリンク
```

グローバルシムリンク:

```
~/.claude/skills/ -> .claude/skills/
```

## 再実行

セットアップスクリプトはいつでも再実行できます。既存のシムリンクは自動的に置き換えられます。

```bash
pnpm run setup:doc-skill
```

---

# バージョニング

> Source: /pj/zudo-doc/ja/docs/guides/versioning

zudo-docは、ドキュメントの複数バージョンを並行して管理することをサポートしています。バージョニングを有効にすると、古い（またはプレリリース）バージョンはバージョンプレフィックス付きURLで配信され、バージョン切り替えがレイアウトに表示されます。

## 概要

バージョニングにより以下が可能になります：

- **最新**のドキュメントを通常通り`/docs/...`で提供
- 古いバージョンを`/v/{version}/docs/...`で提供
- **バージョン切り替え**でユーザーがバージョン間を移動可能
- **バージョンバナー**で古いまたは未リリースのコンテンツを表示

## バージョニングの有効化

バージョニングは**デフォルトで無効**です。有効にするには、`src/config/settings.ts`に`versions`配列を追加します：

```ts

  // ...
  versions: [
    {
      slug: "1.0",
      label: "1.0.0",
      docsDir: "src/content/docs-v1",
      locales: {
        ja: { dir: "src/content/docs-v1-ja" },
      },
      banner: "unmaintained",
    },
  ],
};
```

バージョニングを無効にするには`versions`を`false`に設定（または省略）します：

```ts
versions: false,
```

## 設定リファレンス

各バージョンエントリは以下のプロパティを受け付けます：

| プロパティ | 型 | 必須 | 説明 |
|----------|------|----------|-------------|
| `slug` | string | はい | URLパスで使用されるバージョン識別子（例：`"1.0"`、`"v2"`） |
| `label` | string | はい | バージョン切り替えに表示されるラベル（例：`"1.0.0"`） |
| `docsDir` | string | はい | このバージョンの英語ドキュメント用コンテンツディレクトリ |
| `locales` | object | いいえ | ロケールごとのコンテンツディレクトリ（メインの`locales`設定と同じ形式） |
| `banner` | `"unmaintained"` \| `"unreleased"` \| `false` | いいえ | バージョンページに表示されるバナーの種類 |

## ディレクトリ構造

各バージョンのコンテンツは独自のディレクトリに格納されます。最新（現在の）バージョンはデフォルトの`docsDir`を使用し、古いバージョンは設定で指定されたディレクトリを使用します：

```
src/content/
├── docs/                # 最新バージョン（デフォルト）
├── docs-ja/             # 最新バージョン — 日本語
├── docs-v1/             # バージョン1.0 — 英語
├── docs-v1-ja/          # バージョン1.0 — 日本語
├── docs-v0.9/           # バージョン0.9 — 英語
└── docs-v0.9-ja/        # バージョン0.9 — 日本語
```

各バージョンディレクトリは存在し、有効なMDXコンテンツファイルを含んでいる必要があります。zudo-docは各バージョンに対して個別のAstroコンテンツコレクションを作成するため、ディレクトリが存在しないとビルドエラーが発生します。

## URL構造

最新バージョンはデフォルトのドキュメントURLで配信されます。古いバージョンは`/v/{slug}/`プレフィックスを使用します：

- **最新：** `/docs/getting-started/introduction`
- **バージョン1.0：** `/v/1.0/docs/getting-started/introduction`
- **バージョン0.9：** `/v/0.9/docs/getting-started/introduction`

ロケールを使用する場合、ロケールプレフィックスはバージョンプレフィックスの後に配置されます：

- **最新（日本語）：** `/ja/docs/getting-started/introduction`
- **バージョン1.0（日本語）：** `/v/1.0/ja/docs/getting-started/introduction`

## バージョン切り替え

1つ以上のバージョンが設定されると、**バージョン切り替え**がヘッダーバーとドキュメントコンテンツエリアの両方に自動的に表示されます。現在のバージョンラベルが表示され、最新バージョンを含むすべての利用可能なバージョンへの切り替えリンクが提供されます。

切り替え時は現在のページスラッグが保持されるため、選択したバージョンでも同じトピックのページに遷移します。

古いバージョンにページが存在しない場合、そのバージョンのリンクは自動的に**無効化**（グレーアウトしてクリック不可）され、404ページへのリンクにはなりません。これはビルド時に各バージョンのコンテンツディレクトリをスキャンすることで判定されます。

ドロップダウンの下部には**「すべてのバージョン」**リンクがあり、[バージョン一覧ページ](/ja/docs/versions/)に移動できます。

## バージョン一覧ページ

`/docs/versions/`（日本語は`/ja/docs/versions/`）に専用のバージョン一覧ページが自動生成されます。このページには、設定されたすべてのバージョンがラベル、ステータスバッジ、ドキュメントリンクとともに一覧表示されます。[Docusaurusのバージョンページ](https://docusaurus.io/versions)と同様の構成です。

このページは`settings.ts`の`versions`配列から自動生成されます。手動でのメンテナンスは不要で、設定でバージョンを追加・削除すると一覧ページも自動的に更新されます。

## バージョンバナー

各バージョンは、バージョンの状態をユーザーに知らせるバナーをすべてのページの上部に表示できます。2種類のバナーが利用可能です：

### Unmaintained（メンテナンス終了）

```ts
banner: "unmaintained",
```

ユーザーが古いバージョンのドキュメントを閲覧していることを示す警告スタイルのバナーを表示し、最新バージョンへのリンクを含みます。

### Unreleased（未リリース）

```ts
banner: "unreleased",
```

ユーザーが未リリースバージョンのドキュメントを閲覧していることを示す情報スタイルのバナーを表示し、最新安定バージョンへのリンクを含みます。

### バナーなし

```ts
banner: false,
```

そのバージョンのバナーを無効にします。`banner`を省略した場合のデフォルトです。

更新されなくなったアーカイブバージョンには`"unmaintained"`を、まだリリースされていない機能のドキュメントには`"unreleased"`を使用してください。

## マルチロケール対応

各バージョンは、メインのロケール設定とは独立して独自のロケールディレクトリを定義できます：

```ts
versions: [
  {
    slug: "1.0",
    label: "1.0.0",
    docsDir: "src/content/docs-v1",
    locales: {
      ja: { dir: "src/content/docs-v1-ja" },
    },
    banner: "unmaintained",
  },
],
```

各バージョンとロケールの組み合わせに対して、zudo-docは個別のコンテンツコレクション（例：`docs-v-1.0-ja`）を作成し、対応するページルートを生成します。

## 新しいバージョンの作成

現在のドキュメントを新しいバージョンとしてアーカイブする準備ができたら：

1. **現在のコンテンツディレクトリ**を新しいバージョンディレクトリにコピー：

   ```bash
   cp -r src/content/docs src/content/docs-v2
   ```

2. 該当する場合は**ロケールディレクトリ**もコピー：

   ```bash
   cp -r src/content/docs-ja src/content/docs-v2-ja
   ```

3. **設定にバージョンを追加**：

   ```ts
   versions: [
     {
       slug: "2.0",
       label: "2.0.0",
       docsDir: "src/content/docs-v2",
       locales: {
         ja: { dir: "src/content/docs-v2-ja" },
       },
       banner: "unmaintained",
     },
     // ...既存のバージョン
   ],
   ```

4. **現在のドキュメントを更新** — `src/content/docs/`内のファイルが最新バージョンとなります。新しいリリースに合わせて必要に応じて更新してください。

`versions`配列は古いバージョンまたはプレリリースバージョンのみを定義します。現在の最新バージョンは常にメインの`docsDir`を使用し、配列には含まれません。

---

# 変更履歴

> Source: /pj/zudo-doc/ja/docs/changelog

zudo-docの各リリースにおける変更、改善、修正を追跡します。

---

# 画像拡大表示

> Source: /pj/zudo-doc/ja/docs/components/image-enlarge

画像の本来の幅がレンダリング幅（デバイスピクセル比を考慮）より大きい場合、隅に小さな拡大ボタンが表示され、操作可能であることを示すうっすらとした枠線が画像に付きます。隅のボタンだけでなく画像のどこをクリックしてもフルスクリーンダイアログで開きます。

## 横幅の広い画像 — ボタンが表示される

以下の画像は 2400 px 幅で、一般的なコンテンツカラムより大きいサイズです。ブラウザがレンダリングサイズを計測すると、拡大ボタンが表示されます。

![横幅の広いプレースホルダー画像](./image-wide.png)

## 小さな画像 — ボタンは表示されない

この画像は 300 px 幅で、コンテンツカラムに収まります。画像がコンテナより大きくないため、拡大ボタンは非表示のままです。

![小さなプレースホルダー画像](./image-small.png)

## 拡大を無効化する（オプトアウト）

幅が大きい画像でも、特定の画像だけ拡大ボタンを無効にしたい場合は、Markdown のタイトル属性に `"no-enlarge"` を指定します。title 属性はレンダリング後の `` からも削除されるため、ブラウザのツールチップには表示されません。

```md
![alt text](./image.png "no-enlarge")
```

![オプトアウトを適用した横幅の広い画像](./image-opt-out.png "no-enlarge")

## 動作の仕組み

この機能は 2 つの部分で構成されています。

- **ビルド時** — rehype プラグインが、段落内で単独の `` を `` でラップし、非表示の `` を注入します。インラインテキストと混在する画像はラップされません。
- **実行時** — Preact アイランド（`ImageEnlarge`）が `ResizeObserver` を使用して `naturalWidth` と `clientWidth × devicePixelRatio` を比較し、ボタンの `hidden` 属性を切り替えます。`hidden` が外れている間は画像全体がクリック対象となり、ホバー時のフィードバックも表示されるため、画像のどこをクリックしても `` で開きます。**ESC** キー、ビューポート右上の閉じるボタン、または画像の外側をクリックすると閉じられます。

:::note
高 DPI ディスプレイ（例：2× Retina）では、デバイスピクセル比を考慮して拡大ボタンの表示判定が行われます。2000 px の画像が 2× 画面で 1000 CSS px にレンダリングされる場合、`2000 ≤ 1000 × 2` となるため、ボタンは表示されません。
:::

## 設定

画像拡大表示は `src/config/settings.ts` で有効にします。

```ts

  imageEnlarge: true,
};
```

`imageEnlarge: false` に設定すると、機能全体を無効にできます。

## オーバーレイ色のカスタマイズ

拡大ボタンとダイアログの閉じるボタンは、外観を制御するトークンペアを共有しています。

- `image-overlay-bg` — アイコンの背後に 80% の不透明度で描画される背景レイヤーの色。
- `image-overlay-fg` — 背景の上に 100% の不透明度で描画されるアイコンの色。

適切なオーバーレイ色はコンテンツ画像に依存し、サイトによって異なります。デフォルト値はほとんどのケースで機能しますが、3 層カラー戦略（[Color](../reference/color.mdx) を参照）に従い、任意のカラースキームで上書きできます。

```ts
// src/config/color-schemes.ts
"My Scheme": {
  // ...palette, background, foreground, ...
  semantic: {
    imageOverlayBg: 0,    // palette index — deep surface
    imageOverlayFg: 11,   // palette index — light text
    // or a direct color string: imageOverlayBg: "#222"
  },
},
```

Color Tweak Panel（有効時）を使えば、コードを編集せずにこれらのトークンをライブで調整できます。

---

# create-zudo-doc CLI

> Source: /pj/zudo-doc/ja/docs/reference/create-zudo-doc

## 使い方

```bash
create-zudo-doc [project-name] [options]
```

フラグなしで実行すると、対話式ウィザードが起動します。すべてのオプションはフラグで指定でき、非対話的（CI/エージェント）に使用できます。

[セットアッププリセットジェネレーター](/ja/docs/getting-started/setup-preset-generator)を使って、対話的に設定を構成し、JSON プリセットまたは CLI コマンドとしてコピーすることもできます。

## オプション

### プロジェクト

| フラグ | 説明 | デフォルト |
|--------|------|-----------|
| `--name ` | プロジェクト名（または最初の位置引数） | `my-docs` |
| `--lang ` | デフォルト言語コード | `en` |
| `--pm ` | パッケージマネージャー: `pnpm`, `npm`, `yarn`, `bun` | `pnpm` |
| `--[no-]install` | スキャフォールディング後に依存関係をインストール | プロンプト |

### カラースキーム

| フラグ | 説明 | デフォルト |
|--------|------|-----------|
| `--color-scheme-mode ` | `single` または `light-dark` | `light-dark` |
| `--scheme ` | カラースキーム（single モード） | `Dracula` |
| `--light-scheme ` | ライトスキーム（light-dark モード） | `Default Light` |
| `--dark-scheme ` | ダークスキーム（light-dark モード） | `Default Dark` |
| `--default-mode ` | `light` または `dark`（light-dark モード） | `dark` |
| `--[no-]respect-system-preference` | OS のカラースキーム設定を尊重 | `true` |

### 機能

| フラグ | 説明 | デフォルト |
|--------|------|-----------|
| `--[no-]i18n` | 多言語対応 | オフ |
| `--[no-]search` | Pagefind 全文検索 | オン |
| `--[no-]sidebar-filter` | サイドバーのリアルタイムフィルタリング | オン |
| `--[no-]design-token-panel` | スペーシング・フォント・サイズ・カラーの各トークンを編集するタブ型パネル | オフ |
| `--[no-]sidebar-resizer` | ドラッグでサイドバー幅を変更 | オフ |
| `--[no-]sidebar-toggle` | デスクトップサイドバーの表示/非表示 | オフ |
| `--[no-]versioning` | 複数バージョンのドキュメント対応 | オフ |
| `--[no-]claude-resources` | Claude Code ドキュメント生成 | オフ |
| `--[no-]doc-history` | ドキュメント編集履歴 | オフ |
| `--[no-]llms-txt` | LLM 向け llms.txt を生成 | オフ |
| `--[no-]skill-symlinker` | ドキュメントスキルのシンボリックリンク | オフ |
| `--[no-]footer-nav-group` | フッターのナビゲーションリンク | オフ |
| `--[no-]footer-copyright` | フッターの著作権表示 | オフ |
| `--[no-]changelog` | 変更履歴ページ | オフ |

### プリセット

| フラグ | 説明 |
|--------|------|
| `--preset ` | JSON プリセットファイルから設定を読み込み（`"-"` で標準入力） |

`--preset` フラグは[セットアッププリセットジェネレーター](/ja/docs/getting-started/setup-preset-generator)の JSON 出力を受け付けます。プリセットを読み込むと、すべてのプロンプトがスキップされます（`--yes` と同様）。個別の CLI フラグはプリセットの値を上書きします。

### 一般

| フラグ | 説明 |
|--------|------|
| `-y, --yes` | 未指定オプションにデフォルトを使用し、プロンプトをスキップ |
| `-h, --help` | ヘルプメッセージを表示 |

## サポート言語

`--lang` フラグは以下の言語コードを受け付けます:

| コード | 言語 |
|--------|------|
| `en` | 英語 |
| `ja` | 日本語 |
| `zh-cn` | 中国語（簡体字） |
| `zh-tw` | 中国語（繁体字） |
| `ko` | 韓国語 |
| `es` | スペイン語 |
| `fr` | フランス語 |
| `de` | ドイツ語 |
| `pt` | ポルトガル語 |

デフォルト言語は、ルートページ（`/docs/...`）で使用されるロケールを決定します。i18n が有効な場合、セカンダリ言語が自動的に追加されます（デフォルトが英語以外の場合は英語、デフォルトが英語の場合は日本語）。

## 使用例

### 対話モード

```bash
pnpm create zudo-doc
```

### すべてデフォルトで非対話的に実行

```bash
pnpm create zudo-doc my-docs --yes
```

### Dracula テーマの日本語サイト

```bash
pnpm create zudo-doc my-docs --lang ja --scheme Dracula --no-i18n --pm pnpm --install
```

### カスタムスキームの Light/Dark モード

```bash
pnpm create zudo-doc my-docs \
  --color-scheme-mode light-dark \
  --light-scheme "GitHub Light" \
  --dark-scheme "GitHub Dark" \
  --default-mode dark \
  --yes
```

### プリセットファイルの使用

[セットアッププリセットジェネレーター](/ja/docs/getting-started/setup-preset-generator)で JSON プリセットを生成し、ファイルに保存してから CLI に渡します:

```bash
pnpm create zudo-doc --preset setup.json --install
```

標準入力から JSON を直接パイプすることもできます:

```bash
cat setup.json | pnpm create zudo-doc --preset - --install
```

### CI/自動化での使用

```bash
pnpm create zudo-doc my-docs \
  --lang en \
  --scheme Nord \
  --no-i18n \
  --search \
  --no-claude-resources \
  --pm pnpm \
  --install \
  --yes
```

## プログラム API

パッケージはプログラム API もエクスポートしています。オプションオブジェクトは JSON プリセットと同じフィールドに加え、`install` オプションを受け付けます:

```ts

await createZudoDoc({
  projectName: "my-docs",
  defaultLang: "en",
  colorSchemeMode: "light-dark",
  lightScheme: "GitHub Light",
  darkScheme: "GitHub Dark",
  defaultMode: "dark",
  respectPrefersColorScheme: true,
  features: [
    "search",
    "sidebarFilter",
    "sidebarResizer",
    "sidebarToggle",
    "docHistory",
    "footerCopyright",
  ],
  packageManager: "pnpm",
  install: true,
});
```

---

# Smart Break ユーティリティ

> Source: /pj/zudo-doc/ja/docs/reference/smart-break

長いURLやファイルシステムパス — 例えば `packages/create-zudo-doc/templates/base/src/utils/smart-break.tsx` — は任意の文字境界では折り返されません。狭いUI（サイドバーのラベル、パンくず、インラインコード、検索スニペットなど）ではコンテナからあふれたり、レイアウトを本来より広くしてしまいます。

`src/utils/smart-break.tsx` にある smart-break ユーティリティは、パス風に見える文字列のデリミタごとに ``（word-break opportunity）ヒントを挿入することでこの問題を解決します。実際にどこで折り返すかはブラウザが利用可能な幅に応じて判断します。

## 自動適用

zudo-doc のいくつかの表示面では、すでに smart-break が自動的に適用されています。追加の設定は不要です：

- **サイドバーツリーのラベル** — カテゴリ名・ページ名
- **パンくずリスト** — 現在ページまでの経路
- **MDX のリンク** — 本文中のアンカーテキスト
- **MDX のインラインコード** — 本文中のバッククォートスパン
- **検索結果** — 検索ダイアログのタイトルとスニペット
- **ドキュメント履歴** — コミットメッセージの表示

ユーザー入力のパス風文字列を描画するカスタムコンポーネントを書くとき以外は、自分で呼び出す必要はありません。

## 手動適用：`SmartBreak` コンポーネント

Preact アイランド（あるいはプロジェクト内の任意の `.tsx` コンポーネント）では `SmartBreak` コンポーネントを使います。子要素を文字列化し、適切な位置に `` を挿入します：

```tsx

  return (
    
      {path}
    
  );
}
```

`path` がパス風でない場合（通常の文章、`and/or`、`state-of-the-art` など）はそのまま返され、不要な wbr は挿入されません。

## 手動適用：`smartBreakToHtml` ヘルパー

Astro コンポーネントや、HTML 文字列を描画するコードパス（`set:html` や `dangerouslySetInnerHTML` など）では、Preact の VNode を直接マウントできません。その場合は `smartBreakToHtml` を使ってください。HTML エスケープ済みの文字列に、リテラルの `` タグを挿入した結果を返します：

```astro
---

const { label } = Astro.props;
---

```

返される文字列はすでに HTML エスケープ済みなので、そのまま `set:html` に渡しても安全です。

## 判定のしくみ

smart-break は2段階で動作します：まず入力を `isPathLike` ヒューリスティックで判定し、**パス風と判定された場合にのみ**固定のデリミタセットで分割して、セグメント間に `` を挟みながら再結合します。

### デリミタセット

以下の各文字の直後に `` を挿入します：

```
/  \  -  _  .  :  ?  #  &  =
```

これで URL 構造（`://`、`?query=value&other=1`、`#anchor`）、ファイルシステムパス（`/`、`\`）、複合的な識別子（`snake_case`、`kebab-case`、`file.name.ext`）をカバーできます。

### `isPathLike` ヒューリスティック

`isPathLike` は、URL・パス・その他のデリミタ構造に見える文字列に対して `true` を返します：

- `://` を含む（任意の URL）
- `/`、`./`、`../` で始まる（POSIX パス）
- `C:\` や `C:/` のような Windows のドライブ接頭辞で始まる
- 英数字の間にスラッシュが2つ以上ある（ネストされたパス）
- ドメイン風の `a.b` パターンに加えて、どこかにスラッシュを含む

一方、文章に紛れ込んだデリミタには `false` を返します：`and/or`、`well-known`、`state-of-the-art`、`1.2.3-beta.4`、`UI/UX` などです。これらはそのまま通過するので、通常の文章の折り返し挙動が維持されます。

### 実例

次のような入力を考えてみます：

```
packages/create-zudo-doc/templates/base/src/utils/smart-break.tsx
```

`isPathLike` は `true` を返し、`smartBreakToHtml` は概念的に次のような結果を返します：

```html
packages/create-zudo-doc/templates/base/src/utils/smart-break.tsx
```

コンテナが十分広ければブラウザは1行で保ち、狭い場合は最も近い `` の位置で折り返します。常にセグメントの境界で折り返され、セグメントの途中で切られることはありません。

## 使わないほうがよい場面

- 短いラベル（1〜2語）— そもそも折り返す箇所がありません。
- どこでも折り返したくない意図的な単一トークン（決して折り返してはいけないバージョンタグなど）。
- CJK の本文 — このユーティリティはラテン文字のパス風文字列を対象としています。CJK の行折り返しは [CJK対応マークダウン](./cjk-friendly.mdx) プラグインとブラウザ標準の挙動に任せてください。

---

# カラースキームプレビュー

> Source: /pj/zudo-doc/ja/docs/guides/color-scheme-preview

## 概要

カラースキームプレビューは、50種類以上のプリセットカラースキームをブラウズし、リアルタイムでサイトに適用できる機能です。この機能は[Design Token Panel](/ja/docs/reference/design-token-panel)の**Color**タブにあり、タブヘッダーの "Scheme..." ドロップダウンから呼び出します。

## 動作の仕組み

Design Token Panelが有効な状態で **Color** タブを開くと、**"Scheme..."** ドロップダウンが表示され、利用可能なすべてのプリセットが一覧されます。スキームを選択すると:

- プリセットのパレット・ベースカラー・セマンティックカラーをすべて tweak state に読み込む
- 即座にページに反映する
- `localStorage` に保持されるため、ページリロードやナビゲーションを越えて維持される
- ソースファイルは一切変更されず、変更はクライアント側のみに留まる

プリセット読み込み後は、タブのカラーピッカーで個別の色をさらに調整できます。

## Design Token Panelの有効化

`src/config/settings.ts` で `designTokenPanel` を `true` に設定します:

```ts title="src/config/settings.ts"

  designTokenPanel: true,
  // ...
};
```

有効になるとヘッダーバーにパレットアイコンが表示されます。クリックするとパネルが開閉し、**Color** タブ内に "Scheme..." ドロップダウンが現れます。

## 利用可能なカラースキーム

パネルには Dracula、Nord、Solarized Dark、Solarized Light、Catppuccin Mocha、Catppuccin Latte、Tokyo Night、Gruvbox Dark、GitHub Dark、GitHub Light など、50種類以上のプリセットカラースキームが含まれています。

プロジェクトの `color-schemes.ts` にバンドルされているスキームが先頭に表示され、セパレーターを挟んで残りのプリセットが続きます。

各スキームは16色のパレット、背景・前景色、選択色、Shiki のシンタックスハイライトテーマ、および任意のセマンティックカラー上書きを指定します。

スキームプレビューは、最終的なスキームを決定する前にコンテンツがさまざまなテーマでどのように見えるかを素早く評価できるため、開発中に特に便利です。

## 関連項目

- [Design Token Panel](/ja/docs/reference/design-token-panel) — スペーシング・フォント・サイズ・カラー各トークンのインタラクティブなタブ型エディタ

---

# フッター

> Source: /pj/zudo-doc/ja/docs/guides/footer

フッターはすべてのページの下部に表示され、`src/config/settings.ts`の`footer`プロパティで設定できます。複数カラムのリンクレイアウトとオプションの著作権テキストをサポートしています。

## 設定

`src/config/settings.ts`の`footer`プロパティは`FooterConfig`オブジェクトを受け入れます：

```ts
footer: {
  links: [
    {
      title: "Docs",
      items: [
        { label: "Getting Started", href: "/docs/getting-started" },
        { label: "Guides", href: "/docs/guides" },
      ],
    },
    {
      title: "Community",
      items: [
        { label: "GitHub", href: "https://github.com/zudolab/zudo-doc" },
      ],
    },
  ],
  copyright: `Copyright © ${new Date().getFullYear()} Your Name. Built with zudo-doc.`,
} satisfies FooterConfig as FooterConfig | false,
```

### links

フッターに表示されるカラムの配列です。各カラムは`title`とリンクの`items`配列を持ちます。

| プロパティ | 型 | 説明 |
|----------|------|-------------|
| `title` | string | リンクの上に表示されるカラム見出し |
| `items` | `FooterLinkItem[]` | カラム内のリンクアイテムの配列 |

`items`配列の各アイテムは以下のプロパティを持ちます：

| プロパティ | 型 | 説明 |
|----------|------|-------------|
| `label` | string | リンクの表示テキスト |
| `href` | string | リンク先のURL |

外部リンク（`http://`または`https://`で始まるURL）は自動的に新しいタブで開き、`rel="noopener noreferrer"`が付与されます。内部リンクはサイトの設定済みベースパスで解決されます。

### copyright

リンクカラムの下にセンタリングされて表示されるオプションの著作権テキストです。リンクカラムが存在する場合、著作権テキストは上部ボーダーで区切られます。リンクが設定されていない場合は、ボーダーなしで表示されます。

著作権フィールドは**HTMLコンテンツ**をサポートしています。``タグを使用してリンクを含めることができます。著作権内のリンクは自動的に`text-accent`カラーとアンダーラインでスタイリングされます。

```ts
copyright: `Copyright © ${new Date().getFullYear()} Your Name. Built with zudo-doc.`,
```

## カラムの追加

`links`配列にオブジェクトを追加することでカラムを増やせます。フッターはレスポンシブグリッドを使用しており、小さい画面ではカラムが縦に積まれ、大きい画面では横に並びます。

```ts
footer: {
  links: [
    {
      title: "Docs",
      items: [
        { label: "Getting Started", href: "/docs/getting-started" },
        { label: "Guides", href: "/docs/guides" },
      ],
    },
    {
      title: "Community",
      items: [
        { label: "GitHub", href: "https://github.com/zudolab/zudo-doc" },
        { label: "Discord", href: "https://discord.gg/example" },
      ],
    },
    {
      title: "More",
      items: [
        { label: "Blog", href: "https://example.com/blog" },
        { label: "Changelog", href: "/docs/changelog" },
      ],
    },
  ],
  copyright: `Copyright © ${new Date().getFullYear()} My Project.`,
},
```

グリッドレイアウトは大画面で`repeat(auto-fit, minmax(12rem, 1fr))`を使用するため、カラムの幅は利用可能なスペースに基づいて自動的に調整されます。

## フッターの無効化

フッターを完全に削除するには、設定で`footer`を`false`に設定します：

```ts
footer: false as FooterConfig | false,
```

`false`に設定すると、フッターコンポーネントはどのページにもレンダリングされません。

## i18n（ローカライズされたラベル）

フッターのカラムとリンクアイテムは、オプションの`locales`フィールドによるロケール固有のオーバーライドをサポートしています。デフォルト以外のロケールでページがレンダリングされると、フッターはローカライズされたタイトルとラベルを自動的に解決します。内部リンクのhrefにもロケールパスが付与されます（例：`/ja/docs/guides`）。

```ts
footer: {
  links: [
    {
      title: "Docs",
      locales: { ja: { title: "ドキュメント" } },
      items: [
        {
          label: "Getting Started",
          href: "/docs/getting-started",
          locales: { ja: { label: "はじめに" } },
        },
        {
          label: "Guides",
          href: "/docs/guides",
          locales: { ja: { label: "ガイド" } },
        },
      ],
    },
  ],
},
```

各`FooterLinkColumn`は、ロケールごとの`{ title }`オーバーライドを持つオプションの`locales`フィールドを受け入れます。各`FooterLinkItem`は、ロケールごとの`{ label }`オーバーライドを持つオプションの`locales`フィールドを受け入れます。ロケールオーバーライドが存在しない場合、デフォルトの`title`または`label`が使用されます。

外部リンクにはロケールプレフィックスは付与されません。`http://`または`https://`で始まらない内部hrefのみがロケールプレフィックスを受け取ります。

## TypeScript型

フッターの設定は`src/config/settings-types.ts`で定義されている以下のインターフェースを使用します：

```ts
interface FooterLinkItem {
  label: string;
  href: string;
  locales?: Record;
}

interface FooterLinkColumn {
  title: string;
  items: FooterLinkItem[];
  locales?: Record;
}

interface FooterConfig {
  links: FooterLinkColumn[];
  copyright?: string;
}
```

設定の`footer`プロパティは`FooterConfig | false`として型付けされており、設定オブジェクトまたは無効化のための`false`のいずれかを指定できます。

## スタイリング

フッターは一貫したテーマ設定のためにプロジェクトのデザイントークンカラーを使用しています：

- `border-muted` — コンテンツとフッターを区切る上部ボーダー、および著作権の上のディバイダー
- `bg-surface` — フッターの背景
- `text-fg` — カラムタイトル
- `text-muted` — リンクテキストと著作権テキスト
- `text-accent` — リンクホバー時の色

レイアウトはレスポンシブで、モバイルでは1カラム、小さい画面では2カラム、大きい画面ではauto-fitカラムになります。実装の詳細は`src/components/footer.astro`を参照してください。

---

# 変更履歴

> Source: /pj/zudo-doc/ja/docs/guides/changelog

zudo-docには、リリースノートとバージョン履歴を追跡するための変更履歴セクションが含まれています。変更履歴は降順のサイドバーソートを使用するため、最新のエントリが常に先頭に表示されます。

## ディレクトリ構造

変更履歴のエントリは専用のコンテンツディレクトリに格納されます：

```
src/content/docs/
└── changelog/
    ├── _category_.json    # 降順ソート付きカテゴリ設定
    ├── index.mdx          # カテゴリインデックスページ
    ├── 0.2.0.mdx          # 新しいエントリ (sidebar_position: 2)
    └── 0.1.0.mdx          # 古いエントリ (sidebar_position: 1)
```

## カテゴリ設定

`_category_.json`ファイルで降順ソートを設定し、新しいエントリがサイドバーの先頭に表示されるようにします：

```json title="_category_.json"
{
  "label": "Changelog",
  "position": 10,
  "sortOrder": "desc"
}
```

`sortOrder: "desc"`を設定すると、`sidebar_position`の値が大きいエントリが先に表示されます。これにより、新しいバージョンが自然に先頭にソートされます。

## 新しいエントリの追加

新しい変更履歴エントリを追加するには：

1. `src/content/docs/changelog/`にバージョン名のMDXファイルを作成（例：`0.2.0.mdx`）
2. `sidebar_position`を前のエントリより大きい値に設定
3. 日本語コンテンツディレクトリ（`src/content/docs-ja/changelog/`）にファイルをミラー

```mdx title="src/content/docs/changelog/0.2.0.mdx"
---
title: "0.2.0"
description: このリリースの概要。
sidebar_position: 2
---

このリリースの変更概要。

### 機能

- 機能A
- 機能B

### バグ修正

- 問題Xの修正
```

新しいバージョンごとに`sidebar_position`の値を増やしてください。カテゴリ設定の`sortOrder: "desc"`と組み合わせることで、最新のエントリが常にサイドバーの先頭に表示されます。

## エントリのフォーマット

各変更履歴エントリは標準的なMDXファイルです。推奨される構造：

- **タイトル**：バージョン番号（例：`"0.2.0"`）
- **説明**：リリースの簡単な概要
- **コンテンツセクション**：機能、バグ修正、破壊的変更など

強制的なフォーマットはありません。プロジェクトに合った構造を使用してください。上記の例は[Keep a Changelog](https://keepachangelog.com/)に似た一般的な規約に従っています。

## バージョンバンプスクリプト

zudo-docにはバージョン管理を自動化する`scripts/version-bump.sh`スクリプトが含まれています：

```bash
# バージョンをバンプして変更履歴エントリを作成
./scripts/version-bump.sh 0.2.0

# バージョンをバンプして変更履歴エントリを作成し、現在のドキュメントをスナップショット
./scripts/version-bump.sh 1.0.0 --snapshot
```

スクリプトは以下のステップを実行します：

1. `package.json`の`version`フィールドを更新
2. 英語と日本語の両方のディレクトリに変更履歴エントリMDXファイルを作成
3. 正しい`sidebar_position`を自動的に設定（既存エントリからインクリメント）

### ドキュメントスナップショット

`--snapshot`フラグを使用すると、バンプ前に現在のドキュメントをバージョン付きスナップショットとしてアーカイブします。これはzudo-docの[バージョニングシステム](/ja/docs/guides/versioning)と連携します：

1. `src/content/docs/`を`src/content/docs-v{old}/`にコピー
2. `src/content/docs-ja/`を`src/content/docs-v{old}-ja/`にコピー
3. `src/config/settings.ts`に追加するバージョン設定エントリを表示

`--snapshot`フラグは新しいバージョンではなく、**古い**バージョンのドキュメントをアーカイブします。スクリプト実行後、`src/content/docs/`は新しいバージョンを表し、スナップショットは以前の状態を保持します。

## バージョンバンプスキル

[Claude Code](https://claude.com/claude-code)ユーザー向けに、zudo-docにはリリースワークフロー全体をオーケストレーションする`/zudo-doc-version-bump`スキルが含まれています。スクリプトを手動で実行する代わりに、スキルがすべてをエンドツーエンドで処理します：

1. 最後のgitタグ以降のコミットを分析し、カテゴリ分け（破壊的変更、機能、修正、その他）
2. 変更内容に基づいてバージョンバンプの種類（major/minor/patch）を提案
3. `version-bump.sh`を実行して`package.json`を更新し、変更履歴エントリを作成
4. 変更履歴テンプレートに実際のコミット内容を記入（英語・日本語の両方）
5. `pnpm b4push`を実行してビルドを検証
6. コミット、プッシュ、CI待機
7. gitタグとGitHubリリースを作成
8. npm公開のガイド（プライベートパッケージの場合はスキップ）

```bash
# Claude Codeでスキルを実行
/zudo-doc-version-bump

# 提案ステップをスキップしてバンプの種類を指定
/zudo-doc-version-bump patch
```

スキルを使用するには、少なくとも1つの`v*`タグが存在する必要があります。初回リリースの場合は、手動で初期タグを作成してください：`git tag v0.1.0 && git push --tags`。

## ヘッダーナビゲーション

変更履歴セクションはヘッダーナビゲーションからリンクされています。これは`src/config/settings.ts`で設定されます：

```ts
headerNav: [
  // ...その他のアイテム
  { label: "Changelog", labelKey: "nav.changelog", path: "/docs/changelog", categoryMatch: "changelog" },
],
```

## i18n

翻訳されたリリースノートを提供するために、変更履歴エントリを日本語コンテンツディレクトリ（`src/content/docs-ja/changelog/`）にミラーしてください。`_category_.json`とディレクトリ構造は英語版と一致させる必要があります。

---

# 開発ワークフロー

> Source: /pj/zudo-doc/ja/docs/guides/development-workflow

## 開発コマンド

ローカル開発サーバーを起動するコマンドです。

| コマンド | 説明 |
|---|---|
| `pnpm dev` | Astro開発サーバー（ポート4321）とdoc-history-server（ポート4322）を同時に起動 |
| `pnpm dev:astro` | Astro開発サーバーのみ（ポート4321） |
| `pnpm dev:history` | docヒストリーAPIサーバーのみ（ポート4322） |
| `pnpm dev:stable` | ビルドしてからサーブする代替モード（コンテンツファイルの追加・削除時のHMRクラッシュを回避） |
| `pnpm dev:network` | `--host 0.0.0.0`でAstro開発サーバーを起動（LAN経由アクセス用） |

コンテンツファイルを頻繁に追加・削除する場合は`pnpm dev:stable`を使用してください。通常の`pnpm dev`はVite HMRのファイルシステム変更でクラッシュすることがあります。

## ビルド・品質コマンド

| コマンド | 説明 |
|---|---|
| `pnpm build` | 静的HTMLを`dist/`にエクスポート |
| `pnpm check` | Astro型チェック |
| `pnpm b4push` | プッシュ前の検証：フォーマットチェック → 型チェック → ビルド → リンクチェック → E2Eテスト |
| `pnpm format` | MDXおよびAstroファイルのフォーマット |
| `pnpm test:unit` | ユニットテストを実行（Vitest） |
| `pnpm test:e2e` | E2Eテストを実行（Playwright） |

プッシュ前に`pnpm b4push`を実行して、サイト全体のビルド、すべてのリンクの解決、E2Eテストの通過を確認してください。開発サーバーが許容するドキュメント間の壊れたリンクやTypeScriptエラーを検出します。

## コンポーネント開発

zudo-docは3つのコンポーネント階層を使用します。コンポーネントの要件に応じて適切な階層を選んでください。

### Astroコンポーネント

`.astro`ファイルはデフォルトの選択肢です — JavaScriptなし、ビルド時にサーバーレンダリングされます。

Astroコンポーネントの用途：

- レイアウトラッパー
- 静的なUI要素（ヘッダー、フッター、サイドバー）
- ユーザー操作が不要なもの全般

### Preactアイランド

`client:load`アイランドは、クライアントサイドのインタラクティビティが必要な場合にのみ使用します。Preactはcompatモード（`@astrojs/preact` with `compat: true`）で動作するため、コンポーネントはReact形式のインポートとAPIを使用できます。

プロジェクトの現在のアイランド：`toc.tsx`、`mobile-toc.tsx`、`sidebar-toggle.tsx`、`sidebar-tree.tsx`、`theme-toggle.tsx`、`doc-history.tsx`、`color-tweak-panel.tsx`、`color-tweak-export-modal.tsx`。

Preactアイランドの用途：

- スクロールスパイ（TOCのハイライト）
- トグル・ドロワーコンポーネント
- ライブ編集パネル

### コンテンツタイポグラフィコンポーネント

`src/components/content/`に配置されたPreact関数コンポーネントで、`client:`ディレクティブを持ちません — クライアントJavaScriptなしでサーバーレンダリングされます。``を通じてMDX内の標準HTMLエレメントをオーバーライドします。

現在のオーバーライド：見出し（h2〜h4）、段落、リンク、strong、ブロッククォート、リスト（ul/ol）、テーブル。

コンテンツタイポグラフィコンポーネントは、標準MDXのプロズ要素にプロジェクトのデザイントークンを適用したい場合に使用します。

## コンテンツ開発サイクル

新しいドキュメントページを追加する際は以下の手順に従ってください：

1. `src/content/docs/`以下に`title`と`sidebar_position`をフロントマターに含む`.mdx`ファイルを作成します。
2. `## h2`見出しからコンテンツを書き始めます。`# h1`は追加しません — フロントマターの`title`がページのh1としてレンダリングされます。
3. `src/content/docs-ja/`以下に日本語訳を含む対応ファイルを作成します。
4. ENとJAのコードブロックは同一に保ちます — 翻訳するのは周囲のプロズのみです。
5. `pnpm format:mdx`を実行してMDXファイルをフォーマットします。
6. `pnpm build`を実行してサイトが正常にビルドされることを確認します。

フロントマターには必ず`sidebar_position`を設定してください。設定しないとページがアルファベット順に並び、意図した順序にならないことがほとんどです。

利用可能なフロントマターフィールドの一覧については[フロントマターリファレンス](./frontmatter.mdx)を参照してください。

---

# デプロイ

> Source: /pj/zudo-doc/ja/docs/guides/deployment

## 概要

zudo-docは完全な静的サイトジェネレーターです。`pnpm build`の出力はHTML、CSS、JavaScriptファイルのディレクトリであり、どこでもデプロイできます。デフォルトのデプロイ先は**Cloudflare Pages**で、CI/CDの自動化にはGitHub Actionsを使用します。

CIパイプラインは合計ビルド時間を短縮するために並列ジョブに分割されています。サイト生成とドキュメント履歴の抽出は独立したジョブとして実行され、デプロイ前にマージされます。

## Cloudflare Pages

ビルドされたサイトは`wrangler pages deploy`を使用してCloudflare Pagesにデプロイされます。デプロイアーティファクトには以下が含まれます：

- Astroのビルド出力（`dist/`）
- 事前生成されたdocヒストリーJSONファイル（`docHistory`が有効な場合）
- `/`からサイトのベースパスへのリダイレクトルール

`/`からのリダイレクトはビルド出力に含まれる静的な`_redirects`ファイルです。Cloudflare Pagesがネイティブに処理するため、Workerやサーバーロジックは不要です。

## CIパイプラインの構造

プロジェクトでは2つのGitHub Actionsワークフローを使用します。

### 本番環境（`main-deploy.yml`）

`main`へのプッシュでトリガーされます。4つのジョブが実行されます：

1. **build-site** — シャロークローン（`fetch-depth: 1`）、`SKIP_DOC_HISTORY=1 pnpm build`でAstroサイトをビルド
2. **build-history** — フルクローン（`fetch-depth: 0`）、`@zudo-doc/doc-history-server generate`を実行してすべてのコンテンツファイルのgit履歴を事前抽出
3. **deploy** — サイトと履歴のアーティファクトをマージし、Cloudflare Pages（本番環境）にデプロイ
4. **notify** — デプロイステータスをIFTTTウェブフックで通知

**コンカレンシー:** `group: production-deploy, cancel-in-progress: false` — 先行するデプロイはキャンセルされずに完了が許可されます。

### PRチェック（`pr-checks.yml`）

`main`を対象としたプルリクエストでトリガーされます。5つのジョブが実行されます：

1. **typecheck** — `pnpm check`を実行（Astro型チェック）
2. **build-site** — シャロークローン、`SKIP_DOC_HISTORY=1 pnpm build`、その後`check:links`
3. **build-history** — フルクローン、docヒストリーの生成
4. **e2e** — Playwrightエンドツーエンドテストを実行（フルクローン、`SKIP_DOC_HISTORY`なしで履歴をインラインに埋め込み）
5. **preview** — アーティファクトをマージしてCloudflare Pagesにプレビューをデプロイ、PRコメントとしてURLを投稿

**コンカレンシー:** `group: pr-checks-{pr-number}, cancel-in-progress: true` — 古い実行はCIの消費を節約するためにキャンセルされます。

### プレビューデプロイ

各PRは以下のURLにプレビューデプロイを取得します：

```
https://pr-{number}.zudo-doc.pages.dev
```

URLは**preview**ジョブによってPRのコメントとして自動的に投稿されます。

## SKIP_DOC_HISTORY

`SKIP_DOC_HISTORY=1`が設定されると、Astroインテグレーションはビルド中のインライン履歴生成をスキップします。このフラグが必要な理由は、履歴生成にフルgitクローンが必要でありすべてのコミットを走査するため、メインビルドジョブ内で実行するには時間がかかりすぎるためです。

| コンテキスト | 値 | 理由 |
|---|---|---|
| CI `build-site`ジョブ | `SKIP_DOC_HISTORY=1` | 履歴は独立した`build-history`ジョブが生成する |
| CI `e2e`ジョブ | 未設定 | E2Eテストはインラインで履歴機能を検証する |
| ローカル`pnpm build` | 未設定 | 履歴はビルド出力に直接埋め込まれる |

`SKIP_DOC_HISTORY=1`なしでローカルで`pnpm build`を実行すると、履歴生成がインラインで実行されます。遅くなりますが、独立した履歴アーティファクトなしで動作する自己完結型の`dist/`が生成されます。

## ジョブ間のデータ共有

ビルドアーティファクトは`actions/upload-artifact`ではなく**`actions/cache`**を使用してジョブ間で共有されます。キャッシュキーはクロスラン汚染を防ぐために`github.run_id`にスコープされています：

```yaml
key: dist-${{ github.run_id }}
key: doc-history-${{ github.run_id }}
```

**deploy**（または**preview**）ジョブは両方のキャッシュを復元し、`wrangler pages deploy`を呼び出す前に`dist/`ディレクトリをマージします。

ジョブ間のデータ転送に`actions/cache`を使用すること（アーティファクトではなく）は、大きなZIPアーカイブのアップロードとダウンロードのオーバーヘッドを回避します。キャッシュエントリは一時的なイントラランデータに対してより効率的です。

## 必要なシークレット

リポジトリの**Settings → Secrets and variables → Actions**で設定します：

| シークレット | 説明 |
|---|---|
| `CLOUDFLARE_API_TOKEN` | Pagesデプロイ権限を持つCloudflare APIトークン |
| `CLOUDFLARE_ACCOUNT_ID` | CloudflareアカウントID |
| `IFTTT_PROD_NOTIFY` | デプロイ通知用のIFTTTウェブフックURL（オプション） |

`CLOUDFLARE_API_TOKEN`には**Cloudflare Pages: Edit**権限が必要です。アカウント全体へのアクセス権限を付与するのではなく、特定のPagesプロジェクトにスコープすることを推奨します。

---

# Search Worker API

> Source: /pj/zudo-doc/ja/docs/reference/search-worker

大規模なドキュメントベースやAPIコンシューマー向けに、サーバーサイド検索APIを提供するスタンドアロンのCloudflare Workerです。

## 概要

Search Workerは`packages/search-worker/`にあるサブパッケージで、Cloudflare Workerとしてデプロイされます。組み込みのクライアントサイド検索と同じ[MiniSearch](https://lucaong.github.io/minisearch/)エンジンと検索インデックスを使用しますが、Cloudflare Workersランタイム上でサーバーサイドで実行されます。

これは以下の場合に便利です：

- ドキュメントベースがクライアントサイド検索では大きすぎる場合（フルインデックスをブラウザにダウンロードする必要がある）
- 外部コンシューマー（ボット、インテグレーション、CLIツール）に検索APIを提供したい場合
- プログラムによるアクセスのためにサーバーサイド検索が必要な場合

Workerはデプロイ済みのドキュメントサイトから`search-index.json`を取得し、5分のTTLでメモリにキャッシュします。

Search Workerは既存の検索の**追加オプション**であり、置き換えではありません。主要な検索体験は検索ダイアログ（`Ctrl+K` / `Cmd+K`）を通じたクライアントサイドMiniSearchのままです。使い分けについては[使い分けガイド](#使い分けガイド)を参照してください。

## エンドポイント

```
POST /
Content-Type: application/json
```

WorkerはルートURLで応答します。

### リクエストボディ

```ts
interface SearchRequest {
  query: string;
  limit?: number;
}
```

| フィールド | 型       | 必須 | 説明                                                    |
| ---------- | -------- | ---- | ------------------------------------------------------- |
| `query`    | `string` | はい | 検索クエリ文字列。空でないこと、最大500文字。            |
| `limit`    | `number` | いいえ | 返却する最大結果数。デフォルト：20、最大：100。        |

### 成功レスポンス (200)

```ts
interface SearchResponse {
  results: SearchResult[];
  query: string;
  total: number;
}

interface SearchResult {
  id: string;
  title: string;
  url: string;
  description: string;
  score: number;
}
```

例：

```json
{
  "results": [
    {
      "id": "guides/adding-pages",
      "title": "Adding Pages",
      "url": "/docs/guides/adding-pages",
      "description": "Learn how to add new documentation pages",
      "score": 12.5
    }
  ],
  "query": "how to add a page",
  "total": 3
}
```

### エラーレスポンス

| ステータス | 条件                                    |
| ---------- | --------------------------------------- |
| 400        | 無効なJSONボディ                        |
| 400        | `query`が空でない文字列ではない         |
| 400        | `query`が500文字の制限を超えている      |
| 404        | リクエストパスが`/`ではない             |
| 405        | リクエストメソッドがPOSTではない        |
| 429        | レート制限超過（`Retry-After`ヘッダーを含む） |
| 500        | 内部サーバーエラー（インデックス取得失敗等）  |

すべてのエラーレスポンスは`{ "error": string }`形式を使用します。

## 環境設定

### 変数

`wrangler.toml`で`DOCS_SITE_URL`をデプロイ済みのドキュメントサイトに設定します：

```toml title="packages/search-worker/wrangler.toml"
[vars]
DOCS_SITE_URL = "https://your-docs-site.example.com"
RATE_LIMIT_PER_MINUTE = "60"
RATE_LIMIT_PER_DAY = "1000"
```

| 変数 | デフォルト | 説明 |
| ---- | ---------- | ---- |
| `DOCS_SITE_URL` | -- | デプロイ済みのドキュメントサイトURL |
| `RATE_LIMIT_PER_MINUTE` | `60` | IPあたりの1分間の最大リクエスト数 |
| `RATE_LIMIT_PER_DAY` | `1000` | IPあたりの1日の最大リクエスト数 |

Workerは`${DOCS_SITE_URL}/search-index.json`から検索インデックスを取得します。

### KV名前空間

レート制限にはCloudflare KV名前空間を使用します。デプロイ前に作成してください：

```sh
cd packages/search-worker
npx wrangler kv namespace create RATE_LIMIT
```

返却された名前空間IDで`wrangler.toml`の`[[kv_namespaces]]`の`id`を更新します。

### レート制限の動作

WorkerはCloudflareが提供する`cf-connecting-ip`ヘッダーを使用して、IPごとのレート制限を適用します。

- **ベストエフォート適用** -- KVの読み書きはアトミックではないため、同じIPからの同時リクエストが設定された制限をわずかに超える場合があります
- **フェイルオープン** -- KVが利用不可（障害、設定ミス）の場合、リクエストは許可されます。検索の可用性が厳密なレート制限より優先されます
- **無効な設定** -- `RATE_LIMIT_PER_MINUTE`または`RATE_LIMIT_PER_DAY`の非数値はデフォルト（60/分、1000/日）にフォールバックします
- **429レスポンス** -- `Retry-After`ヘッダー（現在のウィンドウがリセットされるまでの秒数）を含み、CORSを通じてブラウザアクセスに公開されます

## デプロイ

### 手動

```sh
cd packages/search-worker
pnpm install
pnpm run deploy
```

### CI/CD

AI Chat Workerのデプロイと同様のGitHub Actionsワークフローを追加できます。`packages/search-worker/`内のファイルが変更された場合に`main`へのプッシュでWorkerをデプロイするワークフローを設定します。

必要なGitHubシークレット：

- `CLOUDFLARE_API_TOKEN` -- Workers書き込み権限を持つCloudflare APIトークン
- `CLOUDFLARE_ACCOUNT_ID` -- CloudflareアカウントID

## 使い分けガイド

| 機能                     | クライアントサイド検索（組み込み） | Search Worker              |
| ------------------------ | ---------------------------------- | -------------------------- |
| ランタイム               | ブラウザ（インメモリ）             | Cloudflare Workers         |
| デプロイ                 | ドキュメントサイトの一部           | 独立したサービス           |
| インデックスダウンロード | フルインデックスをブラウザに送信   | インデックスはサーバーサイドに留まる |
| 最適な用途               | 小〜中規模のドキュメント           | 大規模なドキュメント、APIコンシューマー |
| セットアップ             | 不要（デフォルトで有効）           | Cloudflareアカウント + KV  |
| レイテンシ               | 即時（ローカル）                   | ネットワークラウンドトリップ |
| 検索設定                 | `prefix: true, fuzzy: 0.2, boost: { title: 3, description: 2 }` | 同一 |

両方とも同じ検索インデックス（`search-index.json`）と同じMiniSearch設定を使用するため、結果は一貫しています。

## リクエストフロー

1. CORSプリフライトの処理
2. メソッドチェック（POSTのみ）とパスチェック（`/`のみ）
3. JSONパースとクエリバリデーション（必須、最大500文字）
4. Web Crypto APIによるSHA-256でクライアントIPをハッシュ化
5. KVに対するレート制限チェック
6. ドキュメントサイトから`search-index.json`を取得（5分TTLでキャッシュ）
7. プレフィックス、ファジー、ブースト設定でMiniSearchクエリを実行
8. 結果を返却

## サブパッケージの場所

```
packages/search-worker/
├── src/
│   ├── index.ts        # Workerエントリーポイント — ルーティング、バリデーション、CORS
│   ├── cors.ts         # CORSヘッダー処理
│   ├── rate-limit.ts   # KVによるIPごとのレート制限
│   ├── search.ts       # MiniSearchインデックスローダー + 検索ロジック
│   └── types.ts        # 型定義
├── wrangler.toml       # Cloudflare Worker設定
├── package.json
├── tsconfig.json
└── README.md
```

---

# Doc History Server

> Source: /pj/zudo-doc/ja/docs/reference/doc-history-server

ドキュメントのgit履歴の配信と生成のためのスタンドアロンパッケージです。ローカル開発用のREST APIサーバーとCIビルド用のCLIバッチジェネレーターの2つのモードを持ちます。

## 概要

Doc History Serverは`packages/doc-history-server/`にあるサブパッケージで、[ドキュメント履歴](/ja/docs/guides/doc-history)機能のすべてのgit履歴抽出を処理します。コストの高いgit操作をサイトビルドから分離するために、Astroビルドパイプラインから抽出されました。

2つのモードで動作します：

- **サーバーモード** -- ローカル開発時にHTTPサーバーを実行し、オンデマンドで履歴を配信
- **CLIモード** -- CIの本番ビルドですべての履歴JSONファイルをバッチ生成

この分離により、AstroサイトビルドとHistory生成を独立したジョブとして実行する並列CI戦略が可能になり、合計ビルド時間を短縮します。

## サーバーモード（ローカル開発）

サーバーは設定可能なポート（デフォルト4322）で実行され、REST API経由でドキュメント履歴を配信します。標準の`pnpm dev`セットアップでは、Astroとdoc-history-serverが`run-p`を使用して同時に実行されます。

### サーバーの起動

```sh
pnpm dev -- --content-dir src/content/docs --locale ja:src/content/docs-ja --port 4322
```

### エンドポイント

#### GET /doc-history/\{slug\}.json

ドキュメントの完全なgit履歴を返します。

```
GET /doc-history/guides/writing-docs.json
```

#### GET /doc-history/\{locale\}/\{slug\}.json

ローカライズされたドキュメントの履歴を返します。

```
GET /doc-history/ja/guides/writing-docs.json
```

#### GET /health

ヘルスチェックエンドポイント。

```json
{ "status": "ok" }
```

### サーバーオプション

| フラグ | 必須 | デフォルト | 説明 |
| ------ | ---- | ---------- | ---- |
| `--content-dir` | はい | -- | スキャンするコンテンツディレクトリ |
| `--locale :` | いいえ | -- | 追加のロケールディレクトリ（繰り返し可） |
| `--port` | いいえ | `4322` | HTTPサーバーポート |
| `--max-entries` | いいえ | `50` | ドキュメントあたりの最大gitコミット数 |

### サーバーの動作

- ファイルインデックスは10秒ごとにリフレッシュされ、新しいファイルやリネームされたファイルを自動的に検出します
- クロスオリジン開発アクセス用のCORSヘッダーが含まれます
- 不明なスラッグへのリクエストは`{ "error": "No doc found for slug: ..." }`とともに404を返します

### Astroインテグレーション

開発モードでは、`src/integrations/doc-history.ts`にあるAstroインテグレーションが`/doc-history/*`リクエストをこのサーバーにプロキシします。これにより、ブラウザの履歴パネルはAstro開発サーバーを通じてスタンドアロンサーバーから透過的に取得します。

ルートの`pnpm dev`コマンドは、`run-p`を使用してAstro（ポート4321）とdoc-history-server（ポート4322）を同時に実行します。

## CLIモード（CIビルド）

CLIはすべてのドキュメントの静的JSONファイルを生成します。CIパイプライン向けです。

### 使い方

```sh
pnpm generate -- --content-dir src/content/docs --locale ja:src/content/docs-ja --out-dir dist/doc-history
```

### CLIオプション

| フラグ | 必須 | デフォルト | 説明 |
| ------ | ---- | ---------- | ---- |
| `--content-dir` | はい | -- | スキャンするコンテンツディレクトリ |
| `--locale :` | いいえ | -- | 追加のロケールディレクトリ（繰り返し可） |
| `--out-dir` | はい | -- | 生成されたJSONファイルの出力ディレクトリ |
| `--max-entries` | いいえ | `50` | ドキュメントあたりの最大gitコミット数 |

### CIパイプライン統合

CIパイプラインはAstroサイトビルドと並行して履歴生成を実行します：

- **build-site**ジョブ：シャロークローン（`fetch-depth: 1`）、`SKIP_DOC_HISTORY=1`でAstroサイトをビルド
- **build-history**ジョブ：フルクローン（`fetch-depth: 0`）、`@zudo-doc/doc-history-server generate`を実行
- **deploy**ジョブ：両方のアーティファクトをマージしてCloudflare Pagesにデプロイ

この並列化は、履歴生成がAstroビルドから完全に独立しているため可能です。

`build-history`ジョブはリビジョンデータを抽出するために完全なコミット履歴が必要なため、フルgitクローン（`fetch-depth: 0`）が必要です。`build-site`ジョブは現在のファイル内容のみ必要なため、シャロークローンを使用できます。

## データ形式

### DocHistoryEntry

ドキュメントの単一のgitリビジョンエントリ：

```ts
interface DocHistoryEntry {
  /** 完全なコミットハッシュ（表示には.slice(0, 7)を使用） */
  hash: string;
  /** ISO 8601形式の日付文字列 */
  date: string;
  /** コミット著者名 */
  author: string;
  /** コミットメッセージの1行目 */
  message: string;
  /** このリビジョンでの完全なファイル内容 */
  content: string;
}
```

### DocHistoryData

単一ドキュメントの完全な履歴データ：

```ts
interface DocHistoryData {
  /** ドキュメントスラッグ（ルートパス） */
  slug: string;
  /** リポジトリ内の相対ファイルパス */
  filePath: string;
  /** gitリビジョンエントリ（新しい順） */
  entries: DocHistoryEntry[];
}
```

### 出力構造

生成されるファイルはコンテンツディレクトリ構造をミラーします：

```
dist/doc-history/
  getting-started.json
  guides/writing-docs.json
  guides/color.json
  ja/getting-started.json
  ja/guides/writing-docs.json
```

## アーキテクチャ

### Git操作

履歴抽出は以下の同期gitコール（`execFileSync`）を使用します：

- `git log` -- `--follow`によるリネーム追跡を含むコミットリスト
- `git show` -- 各リビジョンでのファイル内容

`--follow`フラグは複数のフォールバック戦略によるリネーム追跡を行うため、移動やリネームされたドキュメントでも完全な履歴が保持されます。

### 主要な設計判断

- **同期git** -- `execFileSync`は開発サーバー（同一プロセス、逐次処理）で問題ありません。CI CLIも本質的に逐次処理です
- **リポジトリ相対パス** -- APIレスポンスは絶対サーバーパスの漏洩を避けるために相対ファイルパスを使用します
- **スタンドアロンパッケージ** -- 並列CIビルドと独立したバージョニングを可能にするためにAstroから分離されています

## サブパッケージの場所

```
packages/doc-history-server/
├── src/
│   ├── index.ts        # サーバーエントリー — 引数解析、HTTPサーバー起動
│   ├── cli.ts          # CLIエントリー — 引数解析、JSONバッチ生成
│   ├── args.ts         # 境界チェック付き共有引数解析
│   ├── server.ts       # HTTPサーバー（REST APIエンドポイント）
│   ├── git-history.ts  # コアgitロジック（log、show、follow、リネーム追跡）
│   ├── shared.ts       # 共有ヘルパー（getContentDirEntries）
│   └── types.ts        # DocHistoryEntry、DocHistoryData型
├── package.json
├── tsconfig.json
└── README.md
```

---

# レイアウトパターンデモ

> Source: /pj/zudo-doc/ja/docs/guides/layout-demos

`hide_sidebar`と`hide_toc`フロントマターオプションを使用した、さまざまなレイアウト設定のライブ例です。

---

# Claude

> Source: /pj/zudo-doc/ja/docs/claude

Claude Code設定リファレンス。

## 目次

- **[CLAUDE.md](../claude-md/)** (1) — プロジェクト固有の指示
- **[コマンド](../claude-commands/)** (1) — カスタムスラッシュコマンド
- **[スキル](../claude-skills/)** (2) — スキルパッケージ
- **[エージェント](../claude-agents/)** (1) — カスタムサブエージェント

---

# CLAUDE.md

> Source: /pj/zudo-doc/ja/docs/claude-md

このプロジェクトで見つかったCLAUDE.mdファイル。

## ファイル (1)

- [`/CLAUDE.md`](./root/)

---

# コマンド

> Source: /pj/zudo-doc/ja/docs/claude-commands

カスタムスラッシュコマンドリファレンス。

## 利用可能なコマンド (0)

現在、登録されているカスタムスラッシュコマンドはありません。

---

# スキル

> Source: /pj/zudo-doc/ja/docs/claude-skills

スキルリファレンス。

## 利用可能なスキル

- [`check-docs`](./check-docs/) — ドキュメントのリンク切れとフォーマットの問題をチェック
- [`l-update-generator`](./l-update-generator/) — メインのzudo-docプロジェクトとcreate-zudo-docジェネレーターCLIのドリフトを検出・修正
- [`zudo-doc-design-system`](./zudo-doc-design-system/) — zudo-docプロジェクト固有のCSSとコンポーネントルール
- [`zudo-doc-navigation-design`](./zudo-doc-navigation-design/) — zudo-docドキュメントサイトのナビゲーション設計ルール
- [`zudo-doc-translate`](./zudo-doc-translate/) — zudo-docドキュメントの日英翻訳ルール
- [`zudo-doc-version-bump`](./zudo-doc-version-bump/) — バージョン更新とリリースワークフロー
- [`zudo-doc-writing-rules`](./zudo-doc-writing-rules/) — zudo-docコンテンツ(mdx)の執筆ルール

---

# エージェント

> Source: /pj/zudo-doc/ja/docs/claude-agents

サブエージェントリファレンス。

## 利用可能なエージェント (1)

- [`doc-reviewer`](./doc-reviewer/) (sonnet) — ドキュメントの正確性、明確さ、完全性をレビューします。

---

# doc-reviewer

> Source: /pj/zudo-doc/ja/docs/claude-agents/doc-reviewer

**モデル:** `sonnet`

# Doc Reviewerエージェント

ドキュメントレビュー用のエージェントです。MDXドキュメントファイルの品質をレビューします。

## レビューチェックリスト

- タイトルは明確で説明的か？
- コンテンツはタイトルと一致しているか？
- コード例は正しく実行可能か？
- 文章は簡潔で専門用語が少ないか？

## 出力形式

フィードバックは重要度別にグループ化された番号付きリストで提供されます：

- **Critical**：読者を混乱させるエラー
- **Suggestion**：明確さを向上させる改善提案

---

# check-docs

> Source: /pj/zudo-doc/ja/docs/claude-skills/check-docs

# Check Docs

ドキュメントファイルをスキャンして一般的な問題を検出し、見つかった問題を報告します。

## 使用するタイミング

- ドキュメントの変更を公開またはマージする前
- リンク切れを検出するためのレビューワークフローの一環として
- ドキュメント構造を再編成した際にリンクが壊れていないか確認する時

## 動作の仕組み

1. 設定された`docsDir`内のすべての`.mdx`および`.md`ファイルをスキャン
2. 内部リンク切れ（存在しないページへの参照）をチェック
3. フロントマターフィールドの欠落（`title`は必須）をチェック
4. 結果をサマリーとして報告

## 使用例

```bash
/check-docs
```

## 実行されるチェック

- **リンク切れ** — 存在しないファイルを指す内部`[テキスト](./パス)`リンク
- **タイトルの欠落** — フロントマターに`title`がないMDXファイル
- **空のファイル** — フロントマター後にコンテンツがないファイル
- **sidebar_positionの重複** — 同じカテゴリ内で同じposition値を持つ複数のファイル