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

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

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

Example docset with single product:

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

# changelog.yml
rules:
  publish:
    products:
      kibana:
        exclude_types:
          - docs
        exclude_areas:
          - "Elastic Observability solution"
          - "Elastic Security solution"
		

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

:::{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 rules than the docset default

The product ID matching is case-insensitive.

You can 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 areas, you can control the matching mode with match_areas:

• any (default): block if ANY entry area matches the list
• all: block only if ALL entry areas match the list

The match_areas setting inherits from the global rules.match if not specified. Product-level match_areas inherits from the parent publish.match_areas:

rules.match → publish.match_areas → publish.products.{id}.match_areas
		

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

rules:
  # Global publish rules (applies to all products)
  publish:
    # match_areas: any
    exclude_types:
      - docs
      - regression
    exclude_areas:
      - Internal       # Hide entries with "Internal" area
      - Experimental   # Hide entries with "Experimental" area

    # Product-specific rules (override global rules)
    products:
      kibana:
        exclude_types:
          - docs
        exclude_areas:
          - "Elastic Observability solution"
          - "Elastic Security solution"
      cloud-serverless:
        exclude_types:
          - docs
        exclude_areas:
          - "Snapshot and restore"
		

1. Hide documentation entries
2. Hide regression entries

Product-specific rules 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 exclude_types or include_types list filters entries based on their changelog entry type. Matching is case-insensitive.

Example - hide documentation and regression entries:

rules:
  publish:
    exclude_types:
      - docs
      - regression
		

Example - only show feature and bug-fix entries:

rules:
  publish:
    include_types:
      - feature
      - bug-fix
		

The exclude_areas or include_areas list filters entries based on their area/component tags. By default (match_areas: any), an entry is blocked if any of its areas match. With match_areas: all, an entry is blocked only if all of its areas match. Matching is case-insensitive.

Example - hide internal and experimental entries:

rules:
  publish:
    exclude_areas:
      - Internal
      - Experimental
      - Testing
		

Example - only show entries with specific areas, requiring all areas to match:

rules:
  publish:
    match_areas: all
    include_areas:
      - "Search"
      - "Monitoring"
		

The match_areas setting controls how areas are compared. Here is a quick reference:

Product-specific rules can override match_areas:

rules:
  match: any
  publish:
    # inherits match_areas: any from rules.match
    exclude_areas:
      - Internal
    products:
      cloud-serverless:
        match_areas: all
        include_areas:
          - "Search"
          - "Monitoring"
		

You can combine both type and area filters. An entry is blocked if it matches either a blocked type or a blocked area. You can mix exclude and include across fields (for example, exclude_types with include_areas).

rules:
  publish:
    exclude_types:
      - docs
      - deprecation
    exclude_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
rules:
  publish:
    exclude_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
...
		

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.

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