---
title: Publish changelogs
description: The structure of the changelogs and bundle files is designed to be as stable and consistent as possible so that all teams can incorporate it into their...
url: https://docs-v3-preview.elastic.dev/docs-builder/contribute/publish-changelogs
products:
- Elastic Docs Builder
---
# Publish changelogs
The structure of the changelogs and bundle files is designed to be as stable and consistent as possible so that all teams can incorporate it into their workflow.
The process for deriving docs from the bundle files is designed to be a separate workflow, so that content contributors do not need to worry about layout changes over time.
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.
## Include changelogs inline
You can use the [`{changelog}` directive](https://docs-v3-preview.elastic.dev/docs-builder/syntax/changelog) to render all changelog bundles directly in your documentation pages.
```markdown
:::{changelog}
:::
```
By default, the directive renders all bundles from `changelog/bundles/` (relative to the docset root), ordered by semantic version (newest first).
For full documentation and examples, refer to the [{changelog} directive syntax reference](https://docs-v3-preview.elastic.dev/docs-builder/syntax/changelog).
All product-specific filtering must be configured at bundle time via `rules.bundle`. Unlike the `changelog render` command, the directive does not apply `rules.publish`.
## Generate markdown or asciidoc
The `docs-builder changelog render` command creates markdown or asciidoc files from changelog bundles for documentation purposes.
For up-to-date details, use the `-h` command option or refer to [changelog render](https://docs-v3-preview.elastic.dev/docs-builder/cli/changelog/render).
Before you can use this command you must create changelog files and collect them into bundles.
For example, the `docs-builder changelog bundle` command creates a file like this:
```yaml
products:
- product: elasticsearch
target: 9.2.2
entries:
- file:
name: 1765581721-convert-bytestransportresponse-when-proxying-respo.yaml
checksum: d7e74edff1bdd3e23ba4f2f88b92cf61cc7d490a
- file:
name: 1765581721-fix-ml-calendar-event-update-scalability-issues.yaml
checksum: dfafce50c9fd61c3d8db286398f9553e67737f07
- file:
name: 1765581651-break-on-fielddata-when-building-global-ordinals.yaml
checksum: 704b25348d6daff396259216201053334b5b3c1d
```
To create markdown files from this bundle, run the `docs-builder changelog render` command:
```sh
docs-builder changelog render \
--input "/path/to/changelog-bundle.yaml|/path/to/changelogs|elasticsearch|keep-links,/path/to/other-bundle.yaml|/path/to/other-changelogs|kibana|hide-links" \
--title 9.2.2 \
--output /path/to/release-notes \
--subsections
```
Paths in the `--input` option must be absolute paths or use environment variables. Tilde (`~`) expansion is not supported.
For example, the `index.md` output file contains information derived from the changelogs:
```md
## 9.2.2 [elastic-release-notes-9.2.2]
### Fixes [elastic-9.2.2-fixes]
**Network**
* Convert BytesTransportResponse when proxying response from/to local node. [#135873](https://github.com/elastic/elastic/pull/135873)
**Machine Learning**
* Fix ML calendar event update scalability issues. [#136886](https://github.com/elastic/elastic/pull/136886) [#136900](https://github.com/elastic/elastic/pull/136900)
**Aggregations**
* Break on FieldData when building global ordinals. [#108875](https://github.com/elastic/elastic/pull/108875)
```
When a changelog includes multiple values in its `prs` or `issues` arrays, all its links are rendered inline, as shown in the Machine Learning example above.
To comment out the pull request and issue links, for example if they relate to a private repository, add `hide-links` to the `--input` option for that bundle.
This allows you to selectively hide links per bundle when merging changelogs from multiple repositories.
When `hide-links` is set, all PR and issue links for affected changelogs are hidden together.
If you have changelogs with `feature-id` values and you want them to be omitted from the output, use the `--hide-features` option. Feature IDs specified via `--hide-features` are **merged** with any `hide-features` already present in the bundle files. This means both CLI-specified and bundle-embedded features are hidden in the output.
To create an asciidoc file instead of markdown files, add the `--file-type asciidoc` option:
```sh
docs-builder changelog render \
--input "./changelog-bundle.yaml,./changelogs,elasticsearch" \
--title 9.2.2 \
--output ./release-notes \
--file-type asciidoc \
--subsections
```
## Release highlights
The `highlight` field allows you to mark changelogs that should appear in a dedicated highlights page.
Highlights are most commonly used for major or minor version releases to draw attention to the most important changes.
When you set `highlight: true` in a changelog:
- It appears in both the highlights page (`highlights.md`) and its normal type section (for example "Features and enhancements")
- The highlights page is only created when at least one changelog has `highlight: true` (unlike other special pages like `known-issues.md` which are always created)
- Highlights can be any type of changelog (features, enhancements, bug fixes, etc.)
Example changelog with highlight:
```yaml
type: feature
products:
- product: elasticsearch
target: 9.3.0
lifecycle: ga
title: New Cloud Connect UI for self-managed installations
description: Adds Cloud Connect functionality to Kibana, which allows you to use cloud solutions like AutoOps and Elastic Inference Service in your self-managed Elasticsearch clusters.
highlight: true
```
When rendering, changelogs with `highlight: true` are collected from all types and rendered in a dedicated highlights section.
In markdown output, this creates a separate `highlights.md` file.
In asciidoc output, highlights appear as a dedicated section in the single asciidoc file.