# 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,
  colorTweakPanel: true,
  docMetainfo: true,
  docTags: true,
  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`に設定してみてください。

### 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ルーティングにロケールを登録
- 言語切り替えに追加

### 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`

### 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`

### docMetainfo

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

デフォルト：`true`

### docTags

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

デフォルト：`true`

### colorTweakPanel

インタラクティブなカラースキーム調整パネルを有効にします。`true`の場合、ヘッダーにパレットアイコンが表示され、ページ下部に固定位置のパネルを開いて16色パレット、ベーステーマカラー、セマンティックトークンのオーバーライドをリアルタイムで編集できます。変更は`localStorage`に保存されます。

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

使用方法の詳細やカスタムカラースキームのエクスポート方法については[カラー調整パネルガイド](/ja/docs/guides/color-tweak-panel)を参照してください。

### docHistory

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

ビルド時に、すべてのコンテンツファイルのgit履歴が抽出され、JSONファイルとして`dist/doc-history/`に保存されます。開発モードでは、履歴はViteミドルウェア経由で動的に配信されます。

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

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

### claudeResources

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

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

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

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

### 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サポート、Reactアイランド、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`で定義されています。このファイルがデザインシステムの唯一の情報源です。

---

# /CLAUDE.md

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

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

# zudo-doc

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

## Tech Stack

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

## Commands

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

## Key Directories

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

## Conventions

### Components: Astro vs React

- デフォルトで**Astroコンポーネント**（`.astro`）を使用 — JSゼロ、サーバーレンダリング
- **Reactアイランド**（`client:load`）はクライアントサイドのインタラクティビティが必要な場合のみ使用
- 現在のReactアイランド：`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のみ有効 |
| `color-tweak-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()` |
| インポートが見つからない | 無効化された機能のインポートが除去されていない | `strip.ts` |
| settings.tsの型エラー | 設定フィールドが不足または不正 | `settings-gen.ts` |
| コンポーネントが除去済みコンポーネントを参照 | テンプレートの使用箇所が除去されていない | `strip.ts`のパッチパターン |
| 不要な機能ファイルが残っている | ストリップ時にファイルが削除されていない | `strip.ts` |

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

| ファイル | 役割 |
|----------|------|
| `packages/create-zudo-doc/src/scaffold.ts` | テンプレートのコピー、`package.json`の生成 |
| `packages/create-zudo-doc/src/strip.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`パターンがベースライン — 失敗した場合、他のテストの前に修正してください
- `colorTweakPanel`にはCLIフラグがありません — 使用するパターン（`color-tweak-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 + React コンポーネント
│   └── 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` | 右側の目次を非表示 |
| `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]`に自動生成されます。

```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`）と**Reactアイランド**（`.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/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/getting-started/writing-docs

## ドキュメントの作成

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

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

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

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

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

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

## ディレクトリ構造

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

```
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
```

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

## アドモニション

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の機能

ドキュメント内でReactコンポーネントを使用できます。インタラクティブなコンポーネントは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
```

サイドバーは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);
}
```

`@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`（警告） | 警告メッセージ |
| `info` | `p4`（情報） | 情報ハイライト |

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

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

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

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

同じ`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`にあり、各プロパティは明示的に設定されていない場合、デフォルトのパレットスロットにフォールバックします。

## 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のコンポーネント、デザインシステム、カラーアーキテクチャに関する技術リファレンスです。

---

# 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にインスパイアされた3レベルのナビゲーション階層をサポートしています：

- **ヘッダーナビゲーション** — サイトヘッダーのトップレベルタブ（最大カテゴリ）
- **サイドバーカテゴリ** — サイドバーの折りたたみ可能なグループ（第2レベル）
- **サイドバーアイテム** — カテゴリ内の個別ページ（第3レベル）

## 設定

`src/config/settings.ts`でヘッダーナビゲーションアイテムを定義します：

```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` | string | ヘッダーに表示されるテキスト |
| `labelKey` | string（オプション） | 翻訳が利用可能な場合に`label`をオーバーライドする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カテゴリのみが表示されます。

## アクティブ状態

現在のページURLがアイテムの`path`で始まる場合、そのヘッダーナビゲーションアイテムがアクティブとみなされます。例えば、`/docs/guides/configuration`にアクセスすると、URLが`/docs/guides`で始まるため「Guides」タブがアクティブになります。

## モバイル動作

小さな画面（`< 640px`）では、スペースを節約するためにヘッダーナビゲーションアイテムは非表示になります。モバイルではサイドバートグルですべてのナビゲーションにアクセスできます。

---

# サイドバーフィルター

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

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

---

# 数式

> 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倍にランク付け
- **即時結果**：フルインデックスが一度読み込まれ、メモリ内でクエリを実行

---

# 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,
};
```

この機能はビルドを高速に保つため、**デフォルトでは無効**です。

## 履歴ビューアの使用方法

有効にすると、各ドキュメントページの右下にフローティング**History**ボタンが表示されます。

### リビジョンの閲覧

ボタンをクリックするとリビジョンパネルが開きます。右側からスライドインし、現在のドキュメントを変更したすべてのgitコミットが新しい順に表示されます。各エントリには以下が表示されます：

- **コミットハッシュ**（短縮形）
- コミットの**日付**
- **著者**名
- **コミットメッセージ**（1行目）

### リビジョンの比較

2つのリビジョン間のdiffを表示するには：

1. コミットの横にある**A**ボタンをクリックして**A**（古いリビジョン）を選択
2. 別のコミットの横にある**B**ボタンをクリックして**B**（新しいリビジョン）を選択
3. **Compare**ボタンをクリック

diffビューアは**サイドバイサイド比較**を表示します — 左側に古いリビジョン、右側に新しいリビジョン：

- **緑色の背景** — 新しいリビジョンで追加された行（右側）
- **赤色の背景** — 古いリビジョンから削除された行（左側）
- **灰色のセル** — 一方に対応する行がない空のプレースホルダー
- **変更なしの行** — 両側に表示されるコンテキスト

デフォルトでは、Aは2番目に新しいコミットに、Bは最新のコミットに設定されるため、**Compare**をクリックするだけで最新の変更をすぐに比較できます。

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

- **Escape** — 履歴パネルを閉じる
- 別のページに移動するとパネルは自動的に閉じます

## 仕組み

### ビルドモード

`pnpm build`の実行中、Astroインテグレーションがすべてのコンテンツファイルのgit履歴を抽出し、JSONファイルとして`dist/doc-history/`に書き出します。各JSONファイルには、各コミット時のファイル内容を含む単一ドキュメントの完全なリビジョンリストが格納されます。

出力構造はコンテンツディレクトリをミラーします：

```
dist/doc-history/
  getting-started.json
  guides/writing-docs.json
  guides/color.json
  ja/getting-started.json      # ロケールプレフィックス付き
  ja/guides/writing-docs.json
```

### 開発モード

開発モード（`pnpm dev`）では、Viteミドルウェアが履歴リクエストを動的に処理します。履歴パネルを開くと、その場でgitコマンドが実行されます — 事前生成は不要です。これにより、履歴は最新のコミットと常に同期されます。

`docHistory`を有効にするとビルド時間が増加します。すべてのコンテンツファイルのgit履歴を抽出する必要があるためです。多数のファイルと深い履歴を持つ大規模なドキュメントサイトでは、ビルドに顕著な時間が追加される場合があります。デフォルトの上限はドキュメントあたり**50リビジョン**です。

### 本番出力サイズ

zudo-docはサーバーサイドランタイムなしの完全な静的サイトを生成するため、リクエスト時に`git`コマンドを実行するサーバーがありません。代わりに、ビルドステップですべての履歴データを事前抽出し、`dist/doc-history/`ディレクトリに静的JSONファイルとして出力します。

各JSONファイルには**すべてのリビジョンでの完全なファイル内容**（最大50コミット）が含まれます。これにより、合計出力サイズは以下に比例します：

- ドキュメントファイルの数
- ファイルあたりのgitコミット数
- 各リビジョンでの各ファイルのサイズ

小〜中規模のドキュメントサイトでは通常無視できる程度です。深い履歴を持つ大規模サイトでは、`doc-history/`ディレクトリが大幅に増加する可能性があります。これらのファイルはオンデマンドでのみ取得されるため（ユーザーがHistoryボタンをクリックした時）、初期ページ読み込みには影響しません — ただし、デプロイサイズには追加されます。

デプロイサイズが懸念される場合は、本番ビルドでは`docHistory`を無効（`docHistory: false`）にし、ローカル開発時のみ使用することを検討してください。開発時はViteミドルウェア経由で動的に履歴が配信されるため、事前生成コストがかかりません。

## ローカライゼーションサポート

ドキュメント履歴は設定されたすべてのロケールで動作します。各ロケールのコンテンツディレクトリは、ロケールコードがプレフィックスされた独自の履歴ファイルセットを生成します：

- 英語ドキュメント：`/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`で読み込まれるReactアイランドです。つまり、ページがアイドル状態になってからハイドレーションされます。これにより、初期ページ読み込みパフォーマンスに影響しません。

---

# SiteTreeNav

> Source: /pj/zudo-doc/ja/docs/components/site-tree-nav

## 概要

`SiteTreeNav`は、展開可能なカテゴリカードのレスポンシブグリッドでドキュメントツリー全体を表示するReactアイランドコンポーネントです。カテゴリの展開・折りたたみが可能な、サイトマップ形式のドキュメントページ一覧を提供します。

このコンポーネントはMDXコンテンツで直接利用することは**できません**。サーバーサイドのデータ取得が必要なため、Astroページテンプレートでインポートする必要があります。以下のライブデモは、グローバルMDXコンポーネントとして登録された`SiteTreeNavDemo`（Astroラッパー）を使用しています。

## ライブデモ

以下は`SiteTreeNav`でドキュメントツリー全体を表示した例です（[ホームページ](/)と同じ表示）：

## 使い方

`SiteTreeNav`は`src/pages/index.astro`でホームページのサイトマップを表示するために使用されています：

```astro
---

const categoryOrder = settings.headerNav
  .map((n) => n.categoryMatch)
  .filter((v): v is string => !!v);
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);
---

```

このコンポーネントは展開・折りたたみのインタラクティブ機能にReactステートを使用するため、`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ルーティングの登録が自動的に行われます。残りのステップはコンテンツとページルートを提供します。

---

# 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/`ディレクトリに静的テキストファイルとして出力されます。

---

# 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の各リリースにおける変更、改善、修正を追跡します。

---

# create-zudo-doc CLI

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

## 使い方

```bash
create-zudo-doc [project-name] [options]
```

フラグなしで実行すると、対話式ウィザードが起動します。すべてのオプションはフラグで指定でき、非対話的（CI/エージェント）に使用できます。

## オプション

### プロジェクト

| フラグ | 説明 | デフォルト |
|--------|------|-----------|
| `--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 モード） | `GitHub Light` |
| `--dark-scheme ` | ダークスキーム（light-dark モード） | `GitHub Dark` |
| `--default-mode ` | `light` または `dark`（light-dark モード） | `dark` |
| `--[no-]respect-system-preference` | OS のカラースキーム設定を尊重 | `true` |

### 機能

| フラグ | 説明 | デフォルト |
|--------|------|-----------|
| `--[no-]i18n` | 多言語対応 | オフ |
| `--[no-]search` | Pagefind 全文検索 | オン |
| `--[no-]sidebar-filter` | サイドバーのリアルタイムフィルタリング | オン |
| `--[no-]claude-resources` | Claude Code ドキュメント生成 | オフ |

### 一般

| フラグ | 説明 |
|--------|------|
| `-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
```

### CI/自動化での使用

```bash
pnpm create zudo-doc my-docs \
  --lang en \
  --scheme Nord \
  --no-i18n \
  --search \
  --no-claude-resources \
  --pm pnpm \
  --install \
  --yes
```

## プログラム API

パッケージはプログラム API もエクスポートしています:

```ts

await createZudoDoc({
  projectName: "my-docs",
  defaultLang: "en",
  colorSchemeMode: "single",
  singleScheme: "Dracula",
  features: ["search", "sidebarFilter"],
  packageManager: "pnpm",
  install: true,
});
```

---

# カラースキームプレビュー

> Source: /pj/zudo-doc/ja/docs/guides/color-scheme-preview

## 概要

カラースキームプレビューでは、50以上のプリセットカラースキームを閲覧し、リアルタイムでサイトに適用できます。この機能はカラー調整パネルのヘッダーバーにある「Scheme...」ドロップダウンに組み込まれています。

## 仕組み

カラー調整パネルが有効な場合、パネルヘッダーバーに **「Scheme...」** ドロップダウンが表示されます。利用可能なすべてのプリセットスキームが一覧表示されます。スキームを選択すると：

- プリセットのパレット、ベース、セマンティックカラーがすべて調整状態に読み込まれます
- カラーが即座にページに適用されます
- 選択は `localStorage` に保存され、ページのリロードやナビゲーションをまたいで維持されます
- ソースファイルは変更されません — 変更はクライアントサイドのみです

プリセットを読み込んだ後、パネルのカラーピッカーを使用して必要に応じて個々のカラーをさらに調整できます。

## カラー調整パネルの有効化

`src/config/settings.ts` で `colorTweakPanel` を `true` に設定します：

```ts title="src/config/settings.ts"

  colorTweakPanel: true,
  // ...
};
```

有効にすると、ヘッダーバーにパレットアイコンが表示されます。クリックするとパネルの開閉を切り替えます。「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 コードハイライトテーマ、およびオプションのセマンティックカラーオーバーライドを指定します。

スキームプレビューは、最終的なスキームを決定する前に、さまざまなテーマでコンテンツがどのように表示されるかをすばやく評価するのに特に便利です。

## 関連

- [カラー調整パネル](/ja/docs/guides/color-tweak-panel) — ブラウザ上で個々のパレットカラーやセマンティックトークンをインタラクティブに編集

---

# カラー調整パネル

> Source: /pj/zudo-doc/ja/docs/guides/color-tweak-panel

## 概要

カラー調整パネルは、ページ上のすべてのカラー値をリアルタイムで変更できるインタラクティブエディタです。ビューポート下部に固定パネルとして開き、16色パレット、ベーステーマカラー、セマンティックトークンのオーバーライドのコントロールを提供します。

用途：

- 設定ファイルを編集する代わりに、視覚的に新しいカラースキームをデザイン
- カラー変更がサイト全体にどのように影響するかをプレビュー
- 結果を`ColorScheme`オブジェクトとしてエクスポートし、`src/config/color-schemes.ts`に貼り付け

## パネルの有効化

`src/config/settings.ts`で`colorTweakPanel`を`true`に設定します：

```ts title="src/config/settings.ts"

  colorTweakPanel: true,
  // ...
};
```

有効にすると、ヘッダーバーに（検索アイコンの左側に）パレットアイコンが表示されます。クリックするとパネルの開閉を切り替えます。

パネルはオプション機能です。`colorTweakPanel`が`false`（デフォルト）の場合、パネルのコードやFOUC防止スクリプトは出力に含まれません。

## パネルのセクション

パネルは3つのセクションに分かれています：

### パレット（16色）

16色のカラースウォッチを8列のグリッドで表示し、`p0`から`p15`のラベルが付いています。スウォッチをクリックするとネイティブカラーピッカーが開き、そのパレットスロットを変更できます。変更はそのスロットを参照するすべてのCSSカスタムプロパティに即座に適用されます。

### ベーステーマ

5つのベースカラーのコントロール：`bg`（背景）、`fg`（前景）、`cursor`、`sel-bg`（選択背景）、`sel-fg`（選択前景）。これらは`--zd-bg`、`--zd-fg`、`--zd-cursor`、`--zd-sel-bg`、`--zd-sel-fg`に直接マッピングされます。

### セマンティックトークン

10個のセマンティックトークンすべてを、現在の解決済みカラーとデフォルトのパレットマッピングとともに表示します。各トークンはデフォルトのパレットスロット（例：`accent`はデフォルトで`p6`）を表示します。

カラーピッカーを使用して任意のセマンティックトークンをカスタムカラーでオーバーライドできます。オーバーライドされたトークンには、パレットデフォルトに戻すための**reset**リンクが表示されます。

## 永続化

すべての変更は`localStorage`（キー：`zudo-doc-tweak-state`）に保存され、ページ読み込み時やView Transitionナビゲーション中に自動的に再適用されます。初回ペイント前にインラインスクリプトが実行され、FOUC（スタイル未適用コンテンツのフラッシュ）を防止します。

すべての調整をクリアして元のカラースキームに戻すには、パネルヘッダーの**Reset all**をクリックします。

## カラースキームのエクスポート

パネルヘッダーの**Export**ボタンをクリックすると、現在のカラー設定をTypeScriptコードとして表示するモーダルダイアログが開きます。出力は`ColorScheme`インターフェース形式に一致し、`src/config/color-schemes.ts`に直接貼り付けることができます。

**Copy**をクリックしてコードをクリップボードにコピーします。

エクスポートワークフローにより、ブラウザ上で視覚的にスキームをデザインし、プロジェクト設定に恒久的なスキームとして保存できます。

## スキームチューザー

パネルヘッダーバーには **「Scheme...」** ドロップダウンがあり、50以上のプリセットカラースキーム（Dracula、Nord、Solarized、Catppuccin など）を閲覧して読み込むことができます。

プリセットを選択すると：

- プリセットのパレット、ベース、セマンティックカラーがすべて調整状態に読み込まれます
- カラーが即座にページに適用されます
- 選択は `localStorage` に保存され、ページのリロードやナビゲーションをまたいで維持されます
- プリセットを読み込んだ後、必要に応じて個々のカラーをさらに調整できます

パネルヘッダーの **Reset all** をクリックすると、すべての調整を破棄し、`src/config/settings.ts` の元のスキームに戻ります。

---

# フッター

> 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/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

カスタムスラッシュコマンドリファレンス。

## 利用可能なコマンド (1)

- [`/check-docs`](./check-docs/) — ドキュメントのリンク切れとフォーマットの問題をチェック

---

# スキル

> Source: /pj/zudo-doc/ja/docs/claude-skills

スキルリファレンス。

## 利用可能なスキル (2)

- [`check-docs`](./check-docs/) — ドキュメントのリンク切れとフォーマットの問題をチェック
- [`example-skill`](./example-skill/) — zudo-docドキュメント用のスキルフォーマットを示すサンプルスキル。

---

# エージェント

> 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-commands/check-docs

`src/content/docs/`内のすべてのMDXファイルを以下の観点でレビューします：

1. 内部リンク切れ
2. フロントマターの欠落（`title`は必須）
3. 無効なMDX構文（エスケープされていない`<`、`{`、`}`）
4. インデックスページの`sidebar_position`の欠落

結果をチェックリストとして報告します。

---

# 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値を持つ複数のファイル

---

# example-skill

> Source: /pj/zudo-doc/ja/docs/claude-skills/example-skill

# Example Skill

Claude Resourcesインテグレーションがスキルドキュメントを正しく生成することを検証するためのサンプルスキルです。

## 使用するタイミング

- `claude-resources`インテグレーションをテストする時
- 新しいスキルを作成するためのテンプレートとして

## 動作の仕組み

1. `.claude/skills/example-skill/SKILL.md`からスキルが検出される
2. フロントマター（`name`、`description`）が抽出される
3. 本文コンテンツがMDXページとしてレンダリングされる

## 使用例

```bash
/example-skill
```

## 備考

- スキルには`scripts/`、`assets/`、`references/`サブディレクトリを含めることができる
- `description`フロントマターはスキルインデックスページに表示される