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

Product ID for loading product-specific publish blockers 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 block.publish configuration

This automatic fallback means most single-product docsets don't need to specify :product: explicitly - the directive will automatically use the docset's product for publish blocker lookup.

Example docset with single product:

# docset.yml
products:
  - id: kibana
toc:
  - file: release-notes.md
		

# changelog.yml
block:
  product:
    kibana:
      publish:
        types:
          - docs
        areas:
          - "Elastic Observability solution"
          - "Elastic Security solution"
		

With this configuration, the directive will automatically use the kibana product blockers:

:::{changelog}
:::
		

Explicit override:

You can override the automatic product detection by specifying :product: explicitly:

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

This is useful when:

• The docset has multiple products and you want a specific one
• You want to use a different product's blockers than the docset default

The product ID matching is case-insensitive.

You can filter changelog entries from the rendered output using the block.publish or block.product.{productId}.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:
  # Global publish blocker (applies to all products)
  publish:
    types:
      - docs
      - regression
    areas:
      - Internal       # Hide entries with "Internal" area
      - Experimental   # Hide entries with "Experimental" area

  # Product-specific blockers (override global blockers)
  product:
    kibana:
      publish:
        types:
          - docs
        areas:
          - "Elastic Observability solution"
          - "Elastic Security solution"
    cloud-serverless:
      publish:
        types:
          - docs
        areas:
          - "Snapshot and restore"
		

1. Hide documentation entries
2. Hide regression entries

Product-specific blockers are applied automatically when your docset has a single product configured. For docsets with multiple products or to override the automatic detection, specify the :product: option:

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

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

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.

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.

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}

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