﻿---
title: Changelog
description: The {changelog} directive renders all changelog bundles from a folder directly in your documentation pages. This is designed for release notes pages that...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2569/syntax/changelog
---

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

## Syntax

```markdown
:::{changelog}
:::
```

Or with a custom bundles folder:
```markdown
:::{changelog} /path/to/bundles
:::
```


## Default folder structure

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         
```


## Version ordering

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.

## Rendered output

Each bundle renders as a `## {version}` section with subsections beneath:
```markdown
## 0.100.0
### Features and enhancements
...
### Fixes
...

## 0.99.0
### Features and enhancements
...
```


### Section types


| Section                   | Entry type               | Rendering            |
|---------------------------|--------------------------|----------------------|
| Features and enhancements | `feature`, `enhancement` | Grouped by area      |
| Fixes                     | `bug-fix`, `security`    | Grouped by area      |
| Documentation             | `docs`                   | Grouped by area      |
| Regressions               | `regression`             | Grouped by area      |
| Other changes             | `other`                  | Grouped by area      |
| Breaking changes          | `breaking-change`        | Expandable dropdowns |
| Deprecations              | `deprecation`            | Expandable dropdowns |
| Known issues              | `known-issue`            | Expandable dropdowns |

Sections with no entries of that type are omitted from the output.

## Example

The following renders all changelog bundles from the default `changelog/bundles/` folder:
```markdown
:::{changelog}
:::
```


### Result

<changelog>
</changelog>


## When to use the directive vs render command


| Use case                                          | Recommended approach       |
|---------------------------------------------------|----------------------------|
| Release notes page for a product                  | `{changelog}` directive    |
| Generating static markdown files for external use | `changelog render` command |
| Selective rendering of specific versions          | `changelog render` command |

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

## Related

- [Create and bundle changelogs](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2569/contribute/changelog) — Learn how to create changelog entries and bundles
- [`changelog add`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2569/cli/release/changelog-add) — CLI command to create changelog entries
- [`changelog bundle`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2569/cli/release/changelog-bundle) — CLI command to bundle changelog entries
- [`changelog render`](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2569/cli/release/changelog-render) — CLI command to render changelogs to markdown files