zudo-docには、リリースノートとバージョン履歴を追跡するための変更履歴セクションが含まれています。変更履歴は降順のサイドバーソートを使用するため、最新のエントリが常に先頭に表示されます。

## ディレクトリ構造

変更履歴のエントリは専用のコンテンツディレクトリに格納されます：

```
src/content/docs/
└── changelog/
    ├── index.mdx          # Category index page (sets desc sort order)
    ├── 0.2.0.mdx          # Newer entry (sidebar_position: 2)
    └── 0.1.0.mdx          # Older entry (sidebar_position: 1)
```

## カテゴリ設定

`index.mdx` の `category_sort_order` フロントマターで降順ソートを設定し、新しいエントリがサイドバーの先頭に表示されるようにします：

```mdx title="changelog/index.mdx"
---
title: Changelog
sidebar_position: 10
category_sort_order: "desc"
---
```

`category_sort_order: "desc"`を設定すると、`sidebar_position`の値が大きいエントリが先に表示されます。これにより、新しいバージョンが自然に先頭にソートされます。

## 新しいエントリの追加

新しい変更履歴エントリを追加するには：

1. `src/content/docs/changelog/`にバージョン名のMDXファイルを作成（例：`0.2.0.mdx`）
2. `sidebar_position`を前のエントリより大きい値に設定
3. 設定したすべての追加ロケールディレクトリ（例: `src/content/docs-ja/changelog/` と `src/content/docs-de/changelog/`）にファイルをミラー

```mdx title="src/content/docs/changelog/0.2.0.mdx"
---
title: "0.2.0"
description: Short summary of this release.
sidebar_position: 2
---

Summary of changes in this release.

### Features

- Feature A
- Feature B

### Bug Fixes

- Fix for issue X
```

[Dynamic content unavailable in text export]

新しいバージョンごとに`sidebar_position`の値を増やしてください。カテゴリの`index.mdx`の`category_sort_order: "desc"`と組み合わせることで、最新のエントリが常にサイドバーの先頭に表示されます。



## エントリのフォーマット

各変更履歴エントリは標準的なMDXファイルです。zudo-docは[Keep a Changelog](https://keepachangelog.com/)スタイルの構造を推奨しています。このスタイルであれば、エントリをパッケージ向けの`CHANGELOG.md`に変換できるためです：

- **タイトル**：バージョン番号（例：`"0.2.0"`）
- **説明**：リリースの簡単な概要
- **リリース日**：リリース日が判明している場合は、冒頭付近に`Released: YYYY-MM-DD`の行を記載
- **コンテンツセクション**：Added、Changed、Deprecated、Removed、Fixed、Security、Breaking Changes、Features、Bug Fixesなど、人間が書いたグループ化された変更内容

エントリは人間向けに書いてください。生のgitログをそのまま変更履歴ページに貼り付けず、ユーザーに関係する注目すべき変更を短い箇条書きにまとめてください。

## 生成されるパッケージ変更履歴

プロジェクトでは、`changelogs`フィールドで生成される変更履歴の出力先を設定できます。各項目はソースディレクトリと出力ファイルを指定します：

```ts title="zfb.config.ts"
export default defineConfig(
  zudoDoc({
    changelogs: [
      {
        sourceDir: "src/content/docs/changelog",
        outputFile: "packages/zudo-doc/CHANGELOG.md",
        packageName: "@takazudo/zudo-doc",
      },
    ],
  }),
);
```

MDXファイルは引き続き正とするソースです。生成される`CHANGELOG.md`はそれらのページから上書き生成されるため、手動で編集しないでください。zudo-docはフロントマター、import、export、JSXタグ／コンポーネント、MDXコメントを取り除き、`node_modules`内でも読みやすいCommonMarkとして出力します。

エントリ本文中の相対リンクも出力時に書き換えられるため、公開される成果物にリンク切れの href が残ることはありません。同じディレクトリ内の別エントリのソースファイルを指すリンク（例：`[5.15.0](./5.15.0.mdx)`）は、生成される`CHANGELOG.md`内のファイル内アンカーに変換されます。その際、リンクに付いていた`#fragment`は削除されます（サブ見出しのテキストはバージョンをまたいで繰り返し使われるため）。それ以外の相対`.md`／`.mdx`リンク——生成済みのエントリに解決できないもの——はリンクを外し、ラベルのテキストだけを残して href を削除します。著者はこれまでどおりドキュメントサイト向けの相対リンクをMDXに書けばよく、ドキュメントサイト自体の見え方は変わりません。

配列に項目を追加することで、複数の出力先を設定できます。モノレポで複数パッケージそれぞれに独自の変更履歴を持たせたい場合に便利です。

## 複数の変更履歴（マルチパッケージプロジェクト）

モノレポから複数のパッケージを個別に公開する場合は、ネストした変更履歴を使用します。トップレベルのページをランディングページにし、パッケージごとにネストしたカテゴリを用意します：

```
src/content/docs/changelog/
├── index.mdx
├── core/
│   └── index.mdx
└── cli/
    └── index.mdx
```

これにより、`/docs/changelog`、`/docs/changelog/core`、`/docs/changelog/cli`が生成されます。ランディングページにはパッケージカテゴリを一覧表示し、`category_sort_order: "desc"`は設定しません：

```mdx title="changelog/index.mdx"
---
title: Changelog
sidebar_position: 10
---

Release notes for every package in this repository.

<CategoryNav category="changelog" />
```

### パッケージごとに1ページ（デフォルト）

デフォルトでは、ジェネレーターはパッケージごとに1つの`index.mdx`を作成します。パッケージの履歴全体をそのページに置き、`## Unreleased`の後にバージョンごとのセクションを続けます：

```mdx title="changelog/core/index.mdx"
---
title: Core
sidebar_position: 1
---

## Unreleased

### Added

- Work in progress.

## 1.0.0

Released: 2026-08-22

### Added

- Initial release.
```

### バージョンごとに1ファイル

パッケージの`CHANGELOG.md`も出力する場合は、バージョンごとにファイルを分けます。この形式では、パッケージのインデックスで降順を設定し、リリースファイルを表示します：

```
src/content/docs/changelog/core/
├── index.mdx
├── 1.1.0.mdx
└── 1.0.0.mdx
```

```mdx title="changelog/core/index.mdx"
---
title: Core
sidebar_position: 1
category_sort_order: "desc"
---

Release notes for the core package.

<CategoryNav category="changelog/core" />
```

`changelogs`に設定する各パッケージディレクトリには、`index.mdx`以外のリリース別MDXファイルが必要です。`sourceDir`にはトップレベルの`changelog/`ランディングディレクトリではなく、必ずパッケージディレクトリを指定します：

```ts title="zfb.config.ts"
changelogs: [
  {
    sourceDir: "src/content/docs/changelog/core",
    outputFile: "packages/core/CHANGELOG.md",
    packageName: "@acme/core",
  },
  {
    sourceDir: "src/content/docs/changelog/cli",
    outputFile: "packages/cli/CHANGELOG.md",
    packageName: "@acme/cli",
  },
],
```

設定した`sourceDir`からリリースエントリが見つからず、その配下のサブディレクトリにMDXファイルがある場合は、ランディングディレクトリを指定した可能性があるとしてビルド時に警告が表示されます。

[Dynamic content unavailable in text export]

前へ／次へページネーションは`changelog`セクション全体を対象とするため、別のパッケージへまたがることがあります。その遷移が紛らわしい場合は、パッケージ境界のページのフロントマターで`pagination_prev: null`または`pagination_next: null`を設定してください。



### レイアウトの生成

プロジェクトのスキャフォールド時に、パッケージをカンマ区切りで指定します：

```bash
pnpm create zudo-doc my-docs --changelog-packages core,cli
```

`--changelog-packages`は`--changelog`を暗黙的に有効にします。ジェネレーターはランディングページと、各スラッグに対応するパッケージインデックスを作成しますが、`changelogs`の出力設定は追加しません。パッケージの`CHANGELOG.md`を出力するには、対象パッケージをバージョン別ファイル形式に切り替え、パッケージごとに1つの`changelogs`項目を設定してください。

バージョンバンプスキルは、ルートの1つのバージョンをロックステップで管理し、デフォルトですべてのパッケージを更新します。対象パッケージを選択することもできます。選択した1ページ形式の変更履歴には新しいバージョンセクションを追加し、選択したバージョン別ファイル形式のパッケージには新しいバージョンファイルを追加します。パッケージごとの独立したバージョニングには対応していません。

## バージョンバンプスクリプト

zudo-docにはバージョン管理を自動化する`scripts/version-bump.sh`スクリプトが含まれています：

```bash
# Bump version and create changelog entry
./scripts/version-bump.sh 0.2.0

# Bump version, create changelog entry, and snapshot current docs
./scripts/version-bump.sh 1.0.0 --snapshot
```

スクリプトは以下のステップを実行します：

1. `package.json`の`version`フィールドを更新
2. プライマリと設定した各追加ロケールのディレクトリに変更履歴エントリMDXファイルを作成
3. 正しい`sidebar_position`を自動的に設定（既存エントリからインクリメント）

### ドキュメントスナップショット

`--snapshot`フラグを使用すると、バンプ前に現在のドキュメントをバージョン付きスナップショットとしてアーカイブします。これはzudo-docの[バージョニングシステム](https://zudo-doc.takazudomodular.com/ja/docs/guides/versioning)と連携します：

1. `src/content/docs/`を`src/content/docs-v{old}/`にコピー
2. 設定した各追加ロケールディレクトリをコピー（例: `src/content/docs-ja/`を`src/content/docs-v{old}-ja/`、`src/content/docs-de/`を`src/content/docs-v{old}-de/`へ）
3. `src/config/settings.ts`に追加するバージョン設定エントリを表示

[Dynamic content unavailable in text export]

`--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
# Run the skill in Claude Code
/zudo-doc-version-bump

# Or skip the proposal step by specifying the bump type
/zudo-doc-version-bump patch
```

[Dynamic content unavailable in text export]

スキルを使用するには、少なくとも1つの`v*`タグが存在する必要があります。初回リリースの場合は、手動で初期タグを作成してください：`git tag v0.1.0 && git push --tags`。



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

1つの変更履歴には、フラットな`headerNav`アイテムを使用します：

```ts
headerNav: [
  // ...other items
  { label: "Changelog", labelKey: "nav.changelog", path: "/docs/changelog", categoryMatch: "changelog" },
],
```

複数パッケージの変更履歴では、親をドロップダウンにします。`categoryMatch: "changelog"`は親に残し、子からは`categoryMatch`を省略します：

```ts
headerNav: [
  // ...other items
  {
    label: "Changelog",
    path: "/docs/changelog",
    categoryMatch: "changelog",
    children: [
      { label: "Core", path: "/docs/changelog/core" },
      { label: "CLI", path: "/docs/changelog/cli" },
    ],
  },
],
```

ネストした子のアクティブ状態はパスを基準に判定されます。一方、`categoryMatch`は単一のトップレベルディレクトリでサイドバーの範囲を決めます。2つ以上の子が同じ`categoryMatch`を共有すると、サーバーレンダリングされたHTMLではそれらすべてがアクティブになることがあります。`"changelog/core"`のような複数セグメントの値はトップレベルカテゴリに一致せず、サイドバーが空になることがあります。どちらの誤りもビルド時に警告されます。一般的な規則については、[ヘッダーナビゲーション](https://zudo-doc.takazudomodular.com/ja/docs/guides/header-navigation#%E3%83%97%E3%83%AD%E3%83%91%E3%83%86%E3%82%A3-categorymatch-1%E3%81%A4%E3%81%AE%E3%82%AB%E3%83%86%E3%82%B4%E3%83%AA%E9%85%8D%E4%B8%8B%E3%81%AB%E3%83%8D%E3%82%B9%E3%83%88%E3%81%97%E3%81%9F%E5%AD%90%E3%82%92%E7%BD%AE%E3%81%8F)を参照してください。

## i18n

翻訳されたリリースノートを提供するために、変更履歴エントリを設定したすべての追加ロケールディレクトリ（例: `src/content/docs-ja/changelog/` と `src/content/docs-de/changelog/`）にミラーしてください。`index.mdx`とディレクトリ構造はプライマリ版と一致させる必要があります。