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:
:product: kibana
:::
		

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 their area/component within each section. By default, entries are listed without area grouping (matching CLI behavior).

If publish rules with include_areas or exclude_areas are active, the grouping uses the first area in the entry's areas list that is consistent with those rules — the first included area for include_areas rules, or the first non-excluded area for exclude_areas rules. When no publish rules are configured, the first area in the list 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

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

Product ID for loading product-specific publish rules from changelog.yml. The directive resolves the product ID in this order:

1. Explicit :product: option — if specified, uses that product ID
2. Docset's single product — if the docset has exactly one product configured in docset.yml, uses that product ID automatically
3. Global fallback — uses the global rules.publish configuration

When to set :product: explicitly:

Always specify :product: when your docset serves more than one product, or when bundle files can contain entries from multiple products and you have per-product rules configured. Without an explicit :product:, the directive falls back to global rules, which may not apply the right filtering for each product.

:::{changelog}
:product: kibana
:::
		

Single-product docsets:

If your docset.yml declares exactly one product, the directive uses that product ID automatically and you don't need to set :product::

# docset.yml
products:
  - id: kibana
		

:::{changelog}
:::
		

Explicit override:

You can override the automatic product detection at any time:

:::{changelog}
:product: elasticsearch
:::
		

The product ID matching is case-insensitive.

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.

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

rules.publish still works for backward compatibility and can be used to filter changelog entries from the rendered output using the rules.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.

Each field supports exclude (block if matches) or include (block if doesn't match) semantics. You cannot mix both for the same field (for example, you cannot specify both exclude_types and include_types).

For details, refer to the Rules reference.

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}

To override these expectations, set the bundle.directory and bundle.output_directory in the changelog configuration file.

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