zudo-doc
GitHub リポジトリ

検索したい単語を入力

いつでも検索バーを開ける

変更履歴

作成 2026年3月16日更新 2026年8月31日Takeshi Takatsudo

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

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 フロントマターで降順ソートを設定し、新しいエントリがサイドバーの先頭に表示されるようにします：

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

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

Tip

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

エントリのフォーマット

各変更履歴エントリは標準的な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フィールドで生成される変更履歴の出力先を設定できます。各項目はソースディレクトリと出力ファイルを指定します：

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

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

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

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

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

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

changelog/index.mdx
---
title: Changelog
sidebar_position: 10
---

Release notes for every package in this repository.

<CategoryNav category="changelog" />

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

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

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
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/ランディングディレクトリではなく、必ずパッケージディレクトリを指定します：

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ファイルがある場合は、ランディングディレクトリを指定した可能性があるとしてビルド時に警告が表示されます。

Tip

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

レイアウトの生成

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

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スクリプトが含まれています：

# 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のバージョニングシステムと連携します：

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

Note

--snapshotフラグは新しいバージョンではなく、古いバージョンのドキュメントをアーカイブします。スクリプト実行後、src/content/docs/は新しいバージョンを表し、スナップショットは以前の状態を保持します。

バージョンバンプスキル

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

# 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

Note

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

ヘッダーナビゲーション

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

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

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

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"のような複数セグメントの値はトップレベルカテゴリに一致せず、サイドバーが空になることがあります。どちらの誤りもビルド時に警告されます。一般的な規則については、ヘッダーナビゲーションを参照してください。

i18n

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

GitHub でソースを見る

Revision History

Takeshi Takatsudo作成: 2026-03-16T22:41:36+09:00更新: 2026-08-31T16:30:01+09:00

AI Assistant

Ask a question about the documentation.

Preview theme

Loading theme previews…