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 supports the following options:

:::{changelog} /path/to/bundles
:type: all
:subsections:
:::
		

Controls which entry types are displayed. By default, the directive excludes "separated types" (known issues, breaking changes, and deprecations) which are typically shown on their own dedicated pages.

This allows you to create separate pages for different entry types:

# Release Notes

:::{changelog}
:::
		

# Breaking Changes

:::{changelog}
:type: breaking-change
:::
		

# Known Issues

:::{changelog}
:type: known-issue
:::
		

# Deprecations

:::{changelog}
:type: deprecation
:::
		

To show all entries on a single page (previous default behavior):

:::{changelog}
:type: all
:::
		

When enabled, entries are grouped by their area/component within each section. By default, entries are listed without area grouping (matching CLI behavior).

Explicit path to a changelog.yml configuration file. If not specified, the directive auto-discovers from:

1. changelog.yml in the docset root
2. docs/changelog.yml relative to docset root

The configuration can include publish blockers to filter entries by type or area.

You can filter changelog entries from the rendered output using the block.publish configuration in your changelog.yml file. This is useful for hiding entries that shouldn't appear in public documentation, such as internal changes or documentation-only updates.

Create a changelog.yml file in your docset root (or docs/changelog.yml):

block:
  publish:
    types:
      - docs
      - regression
    areas:
      - Internal       # Hide entries with "Internal" area
      - Experimental   # Hide entries with "Experimental" area
		

1. Hide documentation entries
2. Hide regression entries

The types list filters entries based on their changelog entry type. Matching is case-insensitive.

Example - hide documentation and regression entries:

block:
  publish:
    types:
      - docs
      - regression
		

The areas list filters entries based on their area/component tags. An entry is blocked if any of its areas match a blocked area. Matching is case-insensitive.

Example - hide internal and experimental entries:

block:
  publish:
    areas:
      - Internal
      - Experimental
      - Testing
		

You can combine both types and areas filters. An entry is blocked if it matches either a blocked type or a blocked area.

block:
  publish:
    types:
      - docs
      - deprecation
    areas:
      - Internal
		

This configuration will hide:

• All entries with type docs or deprecation
• All entries with the Internal area tag (regardless of type)

For Cloud Serverless releases where you want to hide certain entry types:

# changelog.yml
block:
  publish:
    types:
      - docs
      - deprecation
      - known-issue
		

1. Documentation changes handled separately
2. Deprecations shown on dedicated page
3. Known issues shown on dedicated page

PR and issue links are automatically hidden (commented out) for bundles from private repositories. This is determined by checking the assembler.yml configuration:

• Repositories marked with private: true in assembler.yml will have their links hidden
• For merged bundles (e.g., elasticsearch+kibana), links are hidden if ANY component repository is private
• In standalone builds without assembler.yml, all links are shown by default

Bundles with the same target version/date are automatically merged into a single section. This is useful for Cloud Serverless releases where multiple repositories (e.g., Elasticsearch, Kibana) contribute to a single dated release like 2025-08-05.

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

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

• 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).

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

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

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

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

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

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

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

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.

• Create and bundle changelogs — Learn how to create changelog entries and bundles
• changelog add — CLI command to create changelog entries
• changelog bundle — CLI command to bundle changelog entries
• changelog render — CLI command to render changelogs to markdown files