docs-builder
Loading

Changelog

The {changelog} directive renders all changelog bundles from a folder directly in your documentation pages. This is designed for release notes pages that primarily consist of changelog content.

:::{changelog}
:::

Or with a custom bundles folder:

:::{changelog} /path/to/bundles
:::

The directive expects bundles in changelog/bundles/ relative to the docset root:

docs/
├── _docset.yml
├── changelog/
│   ├── feature-x.yaml
│   ├── bugfix-y.yaml
│   └── bundles/
│       ├── 0.99.0.yaml
│       └── 0.100.0.yaml
└── release-notes.md
  1. Individual changelog entries
  2. Bundled changelogs (by version)
  3. Page with :::{changelog}

Bundles are automatically sorted by semantic version (descending - newest first). This means:

  • 0.100.0 sorts after 0.99.0 (not lexicographically)
  • 1.0.0 sorts after 0.100.0
  • 1.0.0 sorts after 1.0.0-beta

The version is extracted from the first product's target field in each bundle file, or from the filename if not specified.

Each bundle renders as a ## {version} section with subsections beneath:

## 0.100.0
### Features and enhancements
...
### Fixes
...

## 0.99.0
### Features and enhancements
...
Section Entry type Rendering
Features and enhancements feature, enhancement Grouped by area
Fixes bug-fix, security Grouped by area
Documentation docs Grouped by area
Regressions regression Grouped by area
Other changes other Grouped by area
Breaking changes breaking-change Expandable dropdowns
Deprecations deprecation Expandable dropdowns
Known issues known-issue Expandable dropdowns

Sections with no entries of that type are omitted from the output.

The following renders all changelog bundles from the default changelog/bundles/ folder:

:::{changelog}
:::

Known issues and Breaking changes and Deprecations.

CLI

  • Add PR label blockers to changelog creation. #2350 Adds support for configuring PR labels that block changelog creation. This allows teams to mark PRs that should not generate changelog entries (e.g., internal changes, automation, or non-notable fixes).

Assembler

  • Prevent speculative builds for repositories already publishing with non-versioned branches. #2471 Prevents speculative builds from running for repositories that are already publishing with non-versioned branches, avoiding unnecessary build operations.

Build

  • Address F# nullability warnings. #2473 Addresses F# nullability warnings in the codebase to improve code quality and reduce potential null reference issues.

UI

  • Fix HTMX navigation from "Find Pages" dropdown. #2470 Fixes an issue where HTMX navigation was not working correctly when selecting pages from the "Find Pages" dropdown menu.

Documentation

  • This is a sample documentation change to show a full set. This is a sample documentation entry demonstrating how documentation changes are rendered in the changelog directive output.

Rendering

  • This is a sample regression to show a full set. This is a sample regression entry demonstrating how regressions are rendered in the changelog directive output.

Maintenance

  • This is a sample other change to show a full set. This is a sample "other" entry demonstrating how miscellaneous changes are rendered in the changelog directive output.
This is a sample breaking change to show a full set.

This is a sample breaking change entry demonstrating how breaking changes are rendered with dropdowns in the changelog directive output.

CLI

This is a sample deprecation to show a full set.

This is a sample deprecation entry demonstrating how deprecations are rendered with dropdowns in the changelog directive output.

Build

This is a sample known issue to show a full set.

This is a sample known issue entry demonstrating how known issues are rendered with dropdowns in the changelog directive output.

Changelog

  • Introduce changelog automation tooling. #1234 Added CLI commands for managing release notes: changelog add, changelog bundle, and changelog render. This enables automated generation and formatting of release notes from structured YAML files.
Use case Recommended approach
Release notes page for a product {changelog} directive
Generating static markdown files for external use changelog render command
Selective rendering of specific versions changelog render command

The {changelog} directive is ideal for release notes pages that should always show the complete changelog history. For more selective workflows or external publishing, use the changelog render command.