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, deprecations, and highlights) 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
:::
		

# Highlights

:::{changelog}
:type: highlight
:::
		

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

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

When enabled, entries are grouped by "area" within each section. By default, entries are listed without area grouping. If a changelog has multiple area values, only the first one is used.

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

Reserved for future configuration use. The directive does not currently load or apply configuration from this file.

You can filter changelog entries at bundle time using the rules.bundle configuration in your changelog.yml file. This is evaluated during changelog bundle and changelog gh-release, before the bundle is written. Entries that don't match are excluded from the bundle entirely.

The {changelog} directive and the changelog render command both do not apply rules.publish. To filter entries, use rules.bundle at bundle time so entries are excluded before bundling. Both receive only the bundled entries. See the changelog bundle documentation for full syntax.

rules.bundle supports product, type, and area filtering, and per-product overrides. For full syntax, refer to the rules for filtered bundles.

When bundles contain a hide-features field, entries with matching feature-id values are automatically filtered out from the rendered output. This allows you to hide unreleased or experimental features without modifying the bundle at render time.

# Example bundle with hide-features
products:
  - product: elasticsearch
    target: 9.3.0
hide-features:
  - feature:hidden-api
  - feature:experimental
entries:
  - file:
      name: new-feature.yaml
      checksum: abc123
		

When the directive loads multiple bundles, hide-features from all bundles are aggregated and applied to all entries. This means if bundle A hides feature:x and bundle B hides feature:y, both features are hidden in the combined output.

To add hide-features to a bundle, use the --hide-features option when running changelog bundle. For more details, see Hide features in bundles.

Changelog entries can reference multiple pull requests and issues via the prs and issues array fields. When an entry is rendered, all of its links are shown inline:

* Fix ML calendar event update scalability issues. [#136886](https://github.com/elastic/elastic/pull/136886) [#136900](https://github.com/elastic/elastic/pull/136900)
		

PR and issue links are automatically hidden (commented out) for bundles from private repositories. When links are hidden, all PR and issue links for an affected entry are hidden together. 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.

Bundles can have associated amend files that follow the naming pattern {bundle-name}.amend-{N}.yaml (e.g., 9.3.0.amend-1.yaml). When loading bundles, the directive automatically discovers and merges amend files with their parent bundles.

This allows you to add late additions to a release without modifying the original bundle file:

bundles/
├── 9.3.0.yaml
├── 9.3.0.amend-1.yaml
└── 9.3.0.amend-2.yaml
		

1. Parent bundle
2. First amend (auto-merged with parent)
3. Second amend (auto-merged with parent)

All entries from the parent and amend bundles are rendered together as a single release section. The parent bundle's metadata (products, hide-features, repo) is preserved.

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}

The bundle.directory and bundle.output_directory settings in changelog.yml apply to the changelog bundle and changelog gh-release CLI commands. The directive's bundles folder is controlled by its first argument or defaults to changelog/bundles/ relative to the docset root.

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

Note about highlights:

• Highlights only appear when using :type: all (they are excluded from the default view)
• When rendered, highlighted entries appear in BOTH the "Highlights" section AND their original type section (for example, a highlighted feature appears in both "Highlights" and "Features and enhancements")
• The "Highlights" section is only created when at least one entry has highlight: true
• When using :type: highlight, only highlighted entries are shown (no section headers or other content)

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

Bundles created without the --resolve option store file: references (filenames and checksums) instead of embedding entry content inline. When the directive loads such a bundle, it looks up each referenced file to read its content. If a referenced file cannot be found on disk, the directive emits an error and the build fails. This prevents silent data loss where changelog entries would be quietly omitted from rendered release notes without any indication that something was missing.

To fix this, either:

• Restore the missing changelog files, or
• Re-create the bundle with --resolve to embed entry content directly (making the bundle self-contained), or
• Remove the unresolvable entry from the bundle file.

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 remove — CLI command to remove changelog files
• changelog render — CLI command to render changelogs to markdown files