---
title: changelog render
description: Generate markdown or asciidoc files from changelog bundle files. To create the bundle files, use changelog bundle. For details and examples, go to Publish...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/cli/changelog/render
products:
  - Elastic Docs Builder
---

# changelog render
Generate markdown or asciidoc files from changelog bundle files.
To create the bundle files, use [changelog bundle](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/cli/changelog/bundle).
For details and examples, go to [Publish changelogs](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/publish-changelogs).

## Usage

```sh
docs-builder changelog render [options...] [-h|--help]
```


## Options

<definitions>
  <definition term="--config <string?>">
    Optional: Path to the changelog.yml configuration file.
  </definition>
  <definition term="Defaults to docs/changelog.yml.">
  </definition>
  <definition term="Note: The changelog render command does not use rules.publish for filtering. Filtering must be done at bundle time using rules.bundle.">
  </definition>
  <definition term="--hide-features <string[]?>">
    Optional: Filter by feature IDs (comma-separated), or a path to a newline-delimited file containing feature IDs. Can be specified multiple times.
  </definition>
  <definition term="Each occurrence can be either comma-separated feature IDs (e.g., --hide-features "feature:new-search-api,feature:enhanced-analytics") or a file path (e.g., --hide-features /path/to/file.txt).">
  </definition>
  <definition term="When specifying feature IDs directly, provide comma-separated values.">
  </definition>
  <definition term="When specifying a file path, provide a single value that points to a newline-delimited file. The file should contain one feature ID per line.">
  </definition>
  <definition term="Entries with matching feature-id values will be commented out in the output and a warning will be emitted.">
  </definition>
  <definition term="If the bundle contains hide-features values (that is to say, it was created with the --hide-features option), those values are merged with this list and are also hidden.">
  </definition>
  <definition term="--input <string[]>">
    One or more bundle input files.
  </definition>
  <definition term="Each bundle is specified as "bundle-file-path|changelog-file-path|repo|link-visibility" using pipe (|) as delimiter.">
  </definition>
  <definition term="To merge multiple bundles, separate them with commas: --input "bundle1|dir1|repo1|keep-links,bundle2|dir2|repo2|hide-links".">
  </definition>
  <definition term="For example, --input "/path/to/changelog-bundle.yaml|/path/to/changelogs|elasticsearch|keep-links".">
  </definition>
  <definition term="Only bundle-file-path is required for each bundle.">
  </definition>
  <definition term="Use repo if your changelogs do not contain full URLs for the pull requests or issues; otherwise they will be incorrectly derived with "elastic/elastic" in the URL by default.">
  </definition>
  <definition term="Use link-visibility to control whether PR/issue links are shown or hidden for entries from this bundle. Valid values are keep-links (default) or hide-links. Use hide-links for bundles from private repositories. When hide-links is set, all links are hidden for each affected entry — changelog entries can contain multiple PR links (prs) and issue links (issues), and all of them are hidden or shown together.">
  </definition>
  <definition term="Paths support tilde (~) expansion and relative paths.">
  </definition>
</definitions>

<note>
  The `render` command automatically discovers and merges `.amend-*.yaml` files with their parent bundle. For more information about amended bundles, go to [changelog bundle-amend](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/cli/changelog/bundle-amend).
</note>

<definitions>
  <definition term="--file-type <string>">
    Optional: Output file type. Valid values: `"markdown"` or `"asciidoc"`.
  </definition>
  <definition term="Defaults to "markdown".">
  </definition>
  <definition term="When "markdown" is specified, the command generates multiple markdown files (index.md, breaking-changes.md, deprecations.md, known-issues.md).">
  </definition>
  <definition term="When "asciidoc" is specified, the command generates a single asciidoc file with all sections.">
  </definition>
  <definition term="--output <string?>">
    Optional: The output directory for rendered files.
  </definition>
  <definition term="Defaults to current directory.">
  </definition>
  <definition term="--subsections">
    Optional: Group entries by area in subsections.
  </definition>
  <definition term="Defaults to false.">
  </definition>
  <definition term="When enabled, entries are grouped by their area within each section. The first area from each entry's areas list is used for grouping.">
  </definition>
  <definition term="--title <string?>">
    Optional: The title to use for section headers, directories, and anchors in output files.
  </definition>
  <definition term="Defaults to the version in the first bundle.">
  </definition>
  <definition term="If the string contains spaces, they are replaced with dashes when used in directory names and anchors.">
  </definition>
</definitions>

The `changelog render` command does **not** use `rules.publish` for filtering. Filtering must be done at bundle time using `rules.bundle`. For more information, refer to [Publish changelogs](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/contribute/publish-changelogs). For how the directive differs, see the [{changelog} directive syntax reference](https://docs-v3-preview.elastic.dev/elastic/docs-builder/tree/main/syntax/changelog).

## Output formats


### Markdown format

When `--file-type markdown` is specified (the default), the command generates multiple markdown files:
- `index.md` - Contains features, enhancements, bug fixes, security updates, documentation changes, regressions, and other changes
- `breaking-changes.md` - Contains breaking changes
- `deprecations.md` - Contains deprecations
- `known-issues.md` - Contains known issues
- `highlights.md` - Contains highlighted entries (only created when at least one entry has `highlight: true`)


### Asciidoc format

When `--file-type asciidoc` is specified, the command generates a single asciidoc file with all sections:
- Security updates
- Bug fixes
- Highlights (only included when at least one entry has `highlight: true`)
- New features and enhancements
- Breaking changes
- Deprecations
- Known issues
- Documentation
- Regressions
- Other changes

The asciidoc output uses attribute references for links (for example, `{repo-pull}NUMBER[#NUMBER]`).

### Multiple PR and issue links

Changelog entries can reference multiple pull requests and issues using the `prs` and `issues` array fields. When an entry has multiple links, all of them are rendered inline for that entry:
```md
* Fix ML calendar event update scalability issues. [#136886](https://github.com/elastic/elastic/pull/136886) [#136900](https://github.com/elastic/elastic/pull/136900)
```


## Examples


### Render a single bundle

```sh
docs-builder changelog render \
  --input "./docs/changelog/bundles/9.3.0.yaml" \
  --output ./release-notes
```


### Render with tilde expansion

```sh
docs-builder changelog render \
  --input "~/docs/changelog/bundles/9.3.0.yaml|~/docs/changelog|elasticsearch" \
  --output ~/release-notes
```


### Render with relative paths

```sh
docs-builder changelog render \
  --input "./bundles/9.3.0.yaml|./changelog|elasticsearch|keep-links" \
  --file-type markdown \
  --output ./output
```


### Merge multiple bundles

```sh
docs-builder changelog render \
  --input "./bundles/elasticsearch-9.3.0.yaml|./changelog|elasticsearch,./bundles/kibana-9.3.0.yaml|./changelog|kibana" \
  --output ./merged-release-notes
```


### Hide links from private repository bundles

```sh
docs-builder changelog render \
  --input "./public-bundle.yaml|./changelog|elasticsearch|keep-links,./private-bundle.yaml|./private-changelog|internal-repo|hide-links" \
  --output ./release-notes
```