変更履歴

ドキュメントサイトで変更履歴セクションを管理する方法。

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

ディレクトリ構造

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

src/content/docs/
└── changelog/
    ├── index.mdx          # カテゴリインデックスページ（降順ソートを設定）
    ├── 0.2.0.mdx          # 新しいエントリ (sidebar_position: 2)
    └── 0.1.0.mdx          # 古いエントリ (sidebar_position: 1)

カテゴリ設定

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

---
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/）にファイルをミラー

---
title: "0.2.0"
description: このリリースの概要。
sidebar_position: 2
---

このリリースの変更概要。

### 機能

- 機能A
- 機能B

### バグ修正

- 問題Xの修正

エントリのフォーマット

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

• タイトル：バージョン番号（例："0.2.0"）

• 説明：リリースの簡単な概要

• リリース日：リリース日が判明している場合は、冒頭付近にReleased: YYYY-MM-DDの行を記載

• コンテンツセクション：Added、Changed、Deprecated、Removed、Fixed、Security、Breaking Changes、Features、Bug Fixesなど、人間が書いたグループ化された変更内容

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

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

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

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として出力します。

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

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

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

# バージョンをバンプして変更履歴エントリを作成
./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のバージョニングシステムと連携します：

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に追加するバージョン設定エントリを表示

バージョンバンプスキル

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公開のガイド（プライベートパッケージの場合はスキップ）

# Claude Codeでスキルを実行
/zudo-doc-version-bump

# 提案ステップをスキップしてバンプの種類を指定
/zudo-doc-version-bump patch

ヘッダーナビゲーション

変更履歴セクションはヘッダーナビゲーションからリンクされています。これはzfb.config.tsのheaderNavで設定されます：

headerNav: [
  // ...その他のアイテム
  { label: "Changelog", labelKey: "nav.changelog", path: "/docs/changelog", categoryMatch: "changelog" },
],

i18n

翻訳されたリリースノートを提供するために、変更履歴エントリを日本語コンテンツディレクトリ（src/content/docs-ja/changelog/）にミラーしてください。index.mdxとディレクトリ構造は英語版と一致させる必要があります。