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:
:link-visibility: keep-links
:description-visibility: keep-descriptions
:dropdowns:
:::
		

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

Controls how pull request and issue links are shown when the directive applies source-repo-based privacy. Bundles whose repo is listed as private in assembler.yml hide links by default.

This aligns with the changelog render command's link visibility controls.

Controls whether the description text on each changelog record appears in output (bullet body text under each item, or the first paragraph inside a breaking-change, deprecation, known-issue, or highlight entry when :dropdowns: is enabled). This is different from the optional bundle description field (release intro prose after _Released:_), which is always shown when present. See Rendered output.

Contrast with :link-visibility:: :link-visibility: auto hides links when a repo is private. :description-visibility: auto shows richer record description prose when any source repo is private, and hides that prose for bundles that resolve to only public repositories.

Controls how the "separated" entry types (breaking-change, deprecation, known-issue, and entries flagged highlight: true) are rendered. This option only affects these types; features, enhancements, security, bug fixes, documentation, regressions, and other changes are always rendered as flat bulleted lists.

Use dropdowns when breaking-change and deprecation entries have long description, impact, or action prose that benefits from being collapsed by default. Use the flattened default for compact release-notes pages where the list itself is the primary content.

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 or changelog.yaml configuration file, relative to the documentation source directory. If not specified, the directive auto-discovers from these locations (first match wins):

1. changelog.yml or changelog.yaml in the documentation source directory
2. changelog.yml or changelog.yaml in the parent directory (typically the repository root)

Both explicit and auto-discovered paths must resolve within the repository checkout directory and must not traverse symlinks.

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 release-date, description, and hide-features
products:
  - product: elasticsearch
    target: 9.3.0
release-date: "2026-04-09"
description: |
  This release includes new features and bug fixes.

  For more information, see the [release notes](https://example.com/docs).
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, go to Hide features in bundles.

A changelog can reference multiple pull requests and issues in the prs and issues array fields.

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 (for example, elasticsearch+kibana), links are hidden if ANY component repository is private
• In standalone builds without assembler.yml, all links are shown by default

Use :link-visibility: keep-links or hide-links on the {changelog} directive to override this behavior.

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 optional release date, description, and subsections beneath:

## 0.100.0

_Released: 2026-04-09_

This release includes new features and bug fixes.

Download the release binaries: https://github.com/elastic/elasticsearch/releases/tag/v0.100.0

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

## 0.99.0
### Features and enhancements
...
		

When present, the release-date field is rendered immediately after the version heading as italicized text (e.g., _Released: April 9, 2026_). This is purely informative for end-users and is especially useful for components released outside the usual stack lifecycle, such as APM agents and EDOT agents. If the release-date field is present in a bundle, it is always displayed. To control release dates, set release_dates: false at the bundle or profile level in the configuration (see profile configuration); when false, this prevents the date from being written to the bundle during bundling. Defaults to true when omitted.

Bundle descriptions are rendered when present in the bundle YAML file. The description appears after the release date (if any) but before any entry sections. Descriptions support Markdown formatting including links, lists, and multiple paragraphs.

Record descriptions: Each changelog entry may have its own description field in YAML (shown as body text under list items or as the introductory paragraph inside dropdowns). Visibility of these descriptions is controlled with :description-visibility: (defaults to auto; see Option details section). Do not confuse bundle description (intro prose) with per-record description (entry bodies).

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

• Fix HTMX navigation from "Find Pages" dropdown. #2470
• Address F# nullability warnings. #2473
• Prevent speculative builds for repositories already publishing with non-versioned branches. #2471

• This is a sample documentation change to show a full set.

• This is a sample regression to show a full set.

• This is a sample other change to show a full set.

• Introduce changelog automation tooling. #1234

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 — Overview, workflow, and links to detailed guides
• 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