Add asciidoc output option to docs-builder changelog render command

[lcawl]

Summary

• Added --file-type option to changelog render command

Overview

Added support for rendering changelogs to asciidoc format in addition to markdown.
The docs-builder changelog render command now accepts a --file-type option that can output either markdown (default) or asciidoc files.

This functionality is based on the "--file_type" option in https://github.com/elastic/elastic-agent-changelog-tool and the gradlew generateReleaseNotes command in the 8.19 branch of the elasticsearch repo.

Examples

1. Create a bunch of changelogs. For example:
   1. Check out Add file support to docs-builder changelog add --prs option #2453
   2. Create a file that contains a list of PRs. For example, use the list of PRs for 8.19.10:

   https://github.com/elastic/elasticsearch/pull/139679
   https://github.com/elastic/elasticsearch/pull/139712
   https://github.com/elastic/elasticsearch/pull/139442
   https://github.com/elastic/elasticsearch/pull/128429
   https://github.com/elastic/elasticsearch/pull/139966
   https://github.com/elastic/elasticsearch/pull/140118
   https://github.com/elastic/elasticsearch/pull/139989
   https://github.com/elastic/elasticsearch/pull/139569
   https://github.com/elastic/elasticsearch/pull/139788
   https://github.com/elastic/elasticsearch/pull/140046
   https://github.com/elastic/elasticsearch/pull/139894
   https://github.com/elastic/elasticsearch/pull/140149
   https://github.com/elastic/elasticsearch/pull/139221
   https://github.com/elastic/elasticsearch/pull/139669

   3.. Create a configuration file to handle the mapping of labels to areas, for example, use [DOCS] Add changelog configuration file elasticsearch#140141
   4. Refresh the binaries, per https://github.com/elastic/docs-builder/blob/main/README.md. For example:

   ./build.sh clean
   ./build.sh publishbinaries
   cd .artifacts/publish/docs-builder/release/

2. Run the changelog add command:
   ```sh
   ./docs-builder changelog add --prs ~/path/to/8.19.10.txt --repo elasticsearch --owner elastic --products "elasticsearch 8.19.10" --config ~/path/to/changelog.yml --output ~/path/to/elasticsearch/docs/changelog/new/

3. Create a bundle, for example:

   ./docs-builder changelog bundle --all --directory ~/path/to/elasticsearch/docs/changelog/new --output ~/path/to/elasticsearch/docs/changelog/bundles/8.19.10.yaml 

4. Generate the Asciidoc files, for example, in the elasticearch repo:

   ~/Documents/GitHub/docs-builder/.artifacts/publish/docs-builder/release/docs-builder changelog render --input "./changelog/bundles/8.19.10.yaml,./changelog/new,elasticsearch" --output ./reference/release-notes/new --subsections --file-type asciidoc

The resulting file in this case is as follows:

[[release-notes-8.19.10]]
== 8.19.10

[[bug-fixes-8.19.10]]
[float]
=== Bug fixes

Machine Learning::

* Reject updating low-priority model deployments to more than 1 allocation. {es-pull}139989[#139989] 
ES|QL::

* ESQL: Refactor Greatest and Least functions to use evaluator map (#114036). {es-pull}128429[#128429] 
* ESQL: Fix multi-value constant propagation after `STATS`. {es-pull}139442[#139442] 
Data streams::

* Bug fix: the filter of a data stream alias is not always properly removed. {es-pull}139679[#139679] 
* Making sure that failure store document converter does not hang on unexpected exceptions. {es-pull}139712[#139712] 
Recovery::

* Revert "Attempt to clean up index before remote transfer (#115142)". {es-pull}139569[#139569] 
Infra/Core::

* Skip frozen nodes for disk usage check. {es-pull}140118[#140118] 
Snapshot/Restore::

* Register `disable_chunked_encoding` S3 repo setting. {es-pull}139788[#139788] 
Inference::

* [Inference API] Fix auth exception listener not called bug. {es-pull}139966[#139966] 

[[features-enhancements-8.19.10]]
[float]
=== New features and enhancements

ES|QL::

* Expose _tier metadata attribute in ESQL. {es-pull}139894[#139894] 
Network::

* Always log connection failure at WARN level for sniffed node. {es-pull}140149[#140149] 

[[other-8.19.10]]
[float]
=== Other changes

Network::

* Upgrade lz4 dependency to 1.10.1. {es-pull}139221[#139221] 
* Upgrade Netty to 4.1.130.Final. {es-pull}139669[#139669] 

When it is substituted for the existing file, it renders successfully. For example:

Code changes

1. Command Interface (src/tooling/docs-builder/Commands/ChangelogCommand.cs)

• Added --file-type parameter to the Render command
• Validated that file-type is either "markdown" or "asciidoc"
• Updated command description to mention both formats
• Updated error message to reflect both formats

2. Input Model (src/services/Elastic.Documentation.Services/Changelog/ChangelogRenderInput.cs)

• Added FileType property (defaults to "markdown")
• Updated class documentation to mention both formats

3. Service Implementation (src/services/Elastic.Documentation.Services/ChangelogService.cs)

New Methods:

• RenderAsciidoc() - Main method that generates a single asciidoc file with all sections
• RenderEntriesByAreaAsciidoc() - Renders entries grouped by component/area in asciidoc format
• RenderBreakingChangesAsciidoc() - Renders breaking changes in asciidoc format
• RenderDeprecationsAsciidoc() - Renders deprecations in asciidoc format
• RenderKnownIssuesAsciidoc() - Renders known issues in asciidoc format
• FormatPrLinkAsciidoc() - Formats PR links as asciidoc attribute references
• FormatIssueLinkAsciidoc() - Formats issue links as asciidoc attribute references
• ConvertRepoToAttributeName() - Converts repository names to asciidoc attribute format

Modified methods

• RenderChangelogs() - Updated to route to appropriate renderer based on file-type:
  • If asciidoc: calls RenderAsciidoc() to generate a single .asciidoc file
  • If markdown (default): calls existing markdown renderers to generate multiple .md files

4. Asciidoc format details

The asciidoc output follows patterns from Elasticsearch release notes:

• Uses [float] attributes for subsections
• Component names followed by :: (e.g., Data streams::)
• Link format: {repo-pull}NUMBER[#NUMBER] and {repo-issue}NUMBER[#NUMBER]
• All changelog types are handled, including:
  • Security updates
  • Bug fixes
  • New features and enhancements
  • Breaking changes
  • Deprecations
  • Known issues
  • Documentation
  • Regressions
  • Other changes

Documentation updates

1. docs/cli/release/changelog-render.md

• Updated title to mention both markdown and asciidoc
• Added --file-type option documentation
• Updated option descriptions to use generic "files" instead of "markdown files"
• Added "Output formats" section explaining:
  • Markdown format: generates multiple files (index.md, breaking-changes.md, deprecations.md, known-issues.md)
  • Asciidoc format: generates a single .asciidoc file with all sections

2. docs/contribute/changelog.md

• Updated command description to mention both formats
• Updated help text example to include --file-type option
• Added example showing --file-type asciidoc usage
• Updated render_blockers section to mention both formats

Testing

• All existing tests continue to pass (no changes needed)
• Tests compile successfully
• Default behavior (markdown) is unchanged, so existing tests remain valid
• Tests verify markdown output, which remains the default

For new tests added, go to #2452 (comment)

Usage Examples

Markdown (default):

docs-builder changelog render \
  --input "./changelog-bundle.yaml,./changelogs,elasticsearch" \
  --title 9.2.2 \
  --output ./release-notes

Asciidoc:

docs-builder changelog render \
  --input "./changelog-bundle.yaml,./changelogs,elasticsearch" \
  --title 9.2.2 \
  --output ./release-notes \
  --file-type asciidoc

Backward Compatibility

• Fully backward compatible
• --file-type defaults to "markdown" if not specified
• Existing workflows continue to work without changes
• All existing tests pass without modification

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

4. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

Tool(s) and model(s) used: composer-1 agent

[cotti]

I've solved conflicts with the base branch.

Prior to merging this one, can we add some tests?

[lcawl]

I've solved conflicts with the base branch.

Thanks!

Prior to merging this one, can we add some tests?

I made these updates in b9ff19b :

Summary

Added two tests for the docs-builder changelog render command with --file-type asciidoc:

1. RenderChangelogs_WithAsciidocFileType_CreatesSingleAsciidocFile: Verifies that:

   • A single .asciidoc file is created (not multiple files like markdown)
   • The file contains valid asciidoc elements (anchors, headers, entries)
   • No markdown files are created

2. RenderChangelogs_WithAsciidocFileType_ValidatesAsciidocFormat: Verifies that:

   • The asciidoc file has proper structure with anchors ([[release-notes-9.2.0]])
   • Section headers are formatted correctly (==, ===)
   • Entries are formatted as asciidoc lists (starting with *)
   • Different changelog types (features, bug fixes, breaking changes) are rendered correctly
   • No markdown syntax is present

Both tests:

• Follow the existing test patterns in the file
• Use the same test infrastructure (MockFileSystem, TestDiagnosticsCollector, etc.)
• Pass all assertions
• All 78 tests in the test suite pass

The tests verify that the asciidoc render command creates a single, valid asciidoc file as expected.