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. A recommended structure:

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

• Description: A brief summary of the release

• Content sections: Features, Bug Fixes, Breaking Changes, etc.

There is no enforced format — use whatever structure fits your project. The examples above follow a common convention similar to Keep a Changelog.

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 in src/config/settings.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.