Changelog

How to maintain a changelog section in your documentation site.

zudo-doc includes a changelog section for tracking release notes and version history. The changelog uses descending sidebar sort so the newest entries always appear at the top.

Directory Structure

Changelog entries live in a dedicated content directory:

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)

Category Configuration

The index.mdx file configures descending sort order so newer entries appear first in the sidebar:

---
title: Changelog
sidebar_position: 10
category_sort_order: "desc"
---

With category_sort_order: "desc", entries with higher sidebar_position values appear first. This means newer versions naturally sort to the top.

Adding a New Entry

To add a new changelog entry:

1. Create a new MDX file in src/content/docs/changelog/ named after the version (e.g., 0.2.0.mdx)

2. Set the sidebar_position to a value higher than the previous entry

3. Mirror the file in the Japanese content directory (src/content/docs-ja/changelog/)

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

Entry Format

Each changelog entry is a standard MDX file. zudo-doc recommends a Keep a Changelog-style structure because those entries can be converted into package-friendly CHANGELOG.md files:

• Title: The version number (e.g., "0.2.0")

• Description: A brief summary of the release

• Release date: A Released: YYYY-MM-DD line near the top when the release date is known

• Content sections: grouped human-written notes such as Added, Changed, Deprecated, Removed, Fixed, Security, Breaking Changes, Features, and Bug Fixes

Write entries for humans. Do not dump raw git logs into changelog pages; group notable user-facing changes into short bullets.

Generated Package Changelogs

Projects can configure generated changelog outputs with the changelogs field. Each item points at a source directory and an output file:

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

The MDX files remain the source of truth. The generated CHANGELOG.md is overwritten from those pages and should not be edited by hand. zudo-doc strips frontmatter, imports, exports, JSX tags/components, and MDX comments so the output stays readable as CommonMark in node_modules.

Multiple outputs can be configured by adding more items to the array. This is useful when a monorepo wants separate package changelogs, each generated from its own changelog source directory.

Version Bump Script

zudo-doc includes a scripts/version-bump.sh script that automates version management:

# 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

The script performs the following steps:

1. Updates the version field in package.json

2. Creates a changelog entry MDX file in both English and Japanese directories

3. Sets the correct sidebar_position automatically (incremented from existing entries)

Doc Snapshots

When called with --snapshot, the script also archives the current documentation as a versioned snapshot before bumping. This integrates with zudo-doc's versioning system:

1. Copies src/content/docs/ to src/content/docs-v{old}/

2. Copies src/content/docs-ja/ to src/content/docs-v{old}-ja/

3. Prints the version config entry to add to src/config/settings.ts

Version Bump Skill

For Claude Code users, zudo-doc includes a /zudo-doc-version-bump skill that orchestrates the entire release workflow. Instead of running the script manually, the skill handles everything end-to-end:

1. Analyzes commits since the last git tag and categorizes them (breaking, features, fixes, other)

2. Proposes a version bump type (major/minor/patch) based on the changes

3. Runs version-bump.sh to update package.json and create changelog entries

4. Fills in the changelog templates with actual commit details (both EN and JA)

5. Runs pnpm b4push to validate the build

6. Commits, pushes, and waits for CI

7. Creates a git tag and GitHub release

8. Guides you through npm publishing (or skips it for private packages)

# 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

Header Navigation

The changelog section is linked from the header navigation. This is configured via headerNav in zfb.config.ts:

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

i18n

Mirror changelog entries in the Japanese content directory (src/content/docs-ja/changelog/) to provide translated release notes. The index.mdx and directory structure should match the English version.