Publish changelogs

You can use release bundles to generate documentation in multiple formats:

Note

In the short term, the goal is to create docs that can be included in existing release note pages. In the longer term, the goal is to move to more filterable, dynamic pages.

  1. Create a changelog configuration file to define all the default behavior and optional profiles and rules.
  2. Create changelogs that describe all the notable changes.
  3. Bundle the changelogs for product releases.

If you need Asciidoc output (for example, for Elastic 8.x and earlier docs), you can use the docs-builder changelog render command with --file-type asciidoc. For example:

docs-builder changelog render \
  --input "./docs/releases/changelog-bundle.yaml" \
  --output ./docs/release-notes \
  --file-type asciidoc \
  --subsections
  1. You can choose to group the changelogs by their areas. Otherwise, they are grouped only by type.

The command generates a single output file that includes all types of changelogs. For up-to-date details, use the -h command option or refer to changelog render cli command.

If you need Elastic Docs V3 output, you have two options:

The first option is simplest since it requires only a one-time change to your existing release docs.

You can use the {changelog} directive to derive docs from your release bundles. Pass the product name as the directive argument to source bundles from the public CDN:

:::{changelog} my-product
:release-dates:
:highlights:
:::
Important

Before adding this directive, register the product in the active docset configuration file (docset.yml or _docset.yml, depending on the repository):

release_notes:
  - product: my-product

The build fails with an error if the product is not listed there.

Note

The CDN registry for a product is created by the first published bundle. If no release has gone through the bundle pipeline yet, declaring the product under release_notes can fail strict builds with a 404 during build-time prefetch, even when no {changelog} directive exists yet. Wait until the first release has run successfully before adding both the release_notes declaration and the render page.

The directive also supports a local path argument for isolated builds and legacy setups:

:::{changelog} /path/to/bundles
:type: all
:subsections:
:highlights:
:::
  1. If you have separate release note pages for each type, you can edit this option to show the appropriate subset on each page.
  2. You can choose to group the changelogs by their areas. Otherwise, they are grouped only by type.
  3. Add :highlights: when you want a dedicated Highlights section for entries with highlight: true (those entries still appear under their type sections).

There are also options that affect whether to use dropdowns, include descriptions, hide links, and more. For full documentation and examples, refer to the {changelog} directive syntax reference.

If you need Markdown output (in particular, the custom syntax used in Elastic documentation), you can use the docs-builder changelog render command with --file-type markdown. For example:

docs-builder changelog render \
--input "./kibana/docs/releases/cloud-serverless/2026-05-12.yaml" \
--output ./docs-content/release-notes/elastic-cloud-serverless/_snippets \
--config ./docs-content/changelog.yml \
--file-type markdown

The command generates multiple output files:

  • index.md — features, enhancements, bug fixes, security updates, documentation changes, regressions, and other changes
  • breaking-changes.md — breaking changes
  • deprecations.md — deprecations
  • known-issues.md — known issues
  • highlights.md — highlighted entries (only created when at least one entry has highlight: true)

For up-to-date details, use the -h command option or refer to changelog render cli command.

If you are adding this content to existing release note pages, use file inclusions. For example, each time you create a new set of markdown files, you must include it into the existing docs like this:

:::{include} _snippets/2026-05-12/index.md
:::

Since this method requires generating files and adding file inclusions for each release, it's preferable to publish bundles directly.

If you need GitHub Flavored Markdown (GFM) output, you can use the docs-builder changelog render command with --file-type gfm. For example:

docs-builder changelog render \
  --input "./docs/bundles/1.10.0.yaml" \
  --output ./docs/github-release \
  --file-type gfm

The command generates a single GitHub Flavored Markdown file that includes all types of changelogs. It has clean section headings and is suitable for copying and pasting into GitHub releases.

For up-to-date details, use the -h command option or refer to changelog render cli command.