---
title: Publish changelogs
description: You can use release bundles to generate documentation in multiple formats: Asciidoc for Elastic 8.x documentation, Elastic Docs V3 for Elastic 9.x and...
url: https://docs-v3-preview.elastic.dev/docs-builder/data/release-notes/publish
products:
  - Elastic Docs Builder
---

# Publish changelogs
You can use release bundles to generate documentation in multiple formats:
- [Asciidoc](#asciidoc) for Elastic 8.x documentation
- [Elastic Docs V3](#docs-v3) for Elastic 9.x and later documentation
- [GFM](#gfm) for GitHub release notes

<note>
  In the short term, the goal is to create docs that can be included in [existing release note pages](https://www.elastic.co/docs/release-notes).
  In the longer term, the goal is to move to more filterable, dynamic pages.
</note>


## Before you begin

1. [Create a changelog configuration file](https://docs-v3-preview.elastic.dev/docs-builder/data/release-notes/configure) to define all the default behavior and optional profiles and rules.
2. [Create changelogs](https://docs-v3-preview.elastic.dev/docs-builder/data/release-notes/create) that describe all the notable changes.
3. [Bundle the changelogs](https://docs-v3-preview.elastic.dev/docs-builder/data/release-notes/bundle) for product releases.


## Create asciidoc output

If you need Asciidoc output (for example, for [Elastic 8.x and earlier docs](https://www.elastic.co/guide/index.html)), you can use the `docs-builder changelog render` command with  `--file-type asciidoc`.
For example:
```sh
docs-builder changelog render \
  --input "./docs/releases/changelog-bundle.yaml" \
  --output ./docs/release-notes \
  --file-type asciidoc \
  --subsections 
```

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](https://docs-v3-preview.elastic.dev/docs-builder/cli/changelog/render).

## Create Elastic Docs V3 output

If you need [Elastic Docs V3](https://docs-v3-preview.elastic.dev/docs-builder) output, you have two options:
- [Publish bundles directly](#changelog-directive) with the `{changelog}` directive
- [Create markdown output](#render-changelogs) for each release bundle

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

### Publish bundles directly

You can use the [`{changelog}` directive](https://docs-v3-preview.elastic.dev/docs-builder/syntax/changelog) to derive docs from your release bundles.
For example, update your existing release note page to include a directive like this:
```md
:::{changelog} /path/to/bundles
:type: all 
:subsections: 
:::
```

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](https://docs-v3-preview.elastic.dev/docs-builder/syntax/changelog).

### Create markdown output

If you need Markdown output (in particular, the [custom syntax](https://docs-v3-preview.elastic.dev/docs-builder/syntax) used in Elastic documentation), you can use the `docs-builder changelog render` command with `--file-type markdown`.
For example:
```sh
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](https://docs-v3-preview.elastic.dev/docs-builder/cli/changelog/render).
If you are adding this content to existing release note pages, use [file inclusions](https://docs-v3-preview.elastic.dev/docs-builder/syntax/file_inclusion).
For example, each time you create a new set of markdown files, you must include it into the existing docs like this:
```md
:::{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](#changelog-directive).

## Create GFM output

If you need GitHub Flavored Markdown (GFM) output, you can use the `docs-builder changelog render` command with  `--file-type gfm`.
For example:
```sh
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](https://docs-v3-preview.elastic.dev/docs-builder/cli/changelog/render).