Add asciidoc output option to docs-builder changelog render command

docs/cli/release/changelog-render.md

@@ -1,6 +1,6 @@
 # changelog render
 
-Generate markdown files from changelog bundle files.
+Generate markdown or asciidoc files from changelog bundle files.
 
 To create the bundle files, use [](/cli/release/changelog-bundle.md).
 
@@ -25,14 +25,20 @@ docs-builder changelog render [options...] [-h|--help]
 :   **Important**: Paths must be absolute or use environment variables. Tilde (`~`) expansion is not supported.
 
 `--output <string?>`
-:   Optional: The output directory for rendered markdown files.
+:   Optional: The output directory for rendered files.
 :   Defaults to current directory.
 
 `--title <string?>`
-:   Optional: The title to use for section headers, directories, and anchors in output markdown files.
+:   Optional: The title to use for section headers, directories, and anchors in output files.
 :   Defaults to the version in the first bundle.
 :   If the string contains spaces, they are replaced with dashes when used in directory names and anchors.
 
+`--file-type <string>`
+:   Optional: Output file type. Valid values: `"markdown"` or `"asciidoc"`.
+:   Defaults to `"markdown"`.
+:   When `"markdown"` is specified, the command generates multiple markdown files (index.md, breaking-changes.md, deprecations.md, known-issues.md).
+:   When `"asciidoc"` is specified, the command generates a single asciidoc file with all sections.
+
 `--subsections`
 :   Optional: Group entries by area in subsections.
 :   Defaults to false.
@@ -42,7 +48,7 @@ docs-builder changelog render [options...] [-h|--help]
 :   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`).
 :   When specifying feature IDs directly, provide comma-separated values.
 :   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.
-:   Entries with matching `feature-id` values will be commented out in the markdown output and a warning will be emitted.
+:   Entries with matching `feature-id` values will be commented out in the output and a warning will be emitted.
 
 `--config <string?>`
 :   Optional: Path to the changelog.yml configuration file.
@@ -51,3 +57,28 @@ docs-builder changelog render [options...] [-h|--help]
 
 You can configure `render_blockers` in your `changelog.yml` configuration file to automatically block changelog entries from being rendered based on their products, areas, and/or types.
 For more information, refer to [](/contribute/changelog.md#render-blockers).
+
+## 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
+
+### Asciidoc format
+
+When `--file-type asciidoc` is specified, the command generates a single asciidoc file with all sections:
+- Security updates
+- Bug fixes
+- New features and enhancements
+- Breaking changes
+- Deprecations
+- Known issues
+- Documentation
+- Regressions
+- Other changes
+
+The asciidoc output uses attribute references for links (e.g., `{repo-pull}NUMBER[#NUMBER]`) and follows patterns similar to Elasticsearch release notes.

docs/contribute/changelog.md

@@ -97,8 +97,8 @@ Refer to [changelog.yml.example](https://github.com/elastic/docs-builder/blob/ma
 
 ### Render blockers [render-blockers]
 
-You can optionally add `render_blockers` in your changelog configuration to block specific changelog entries from being rendered in markdown output files.
-When you run the `docs-builder changelog render` command, changelog entries that match the specified products and areas/types will be commented out in the markdown output.
+You can optionally add `render_blockers` in your changelog configuration to block specific changelog entries from being rendered in output files.
+When you run the `docs-builder changelog render` command, changelog entries that match the specified products and areas/types will be commented out in the output (markdown or asciidoc).
 
 By default, the `docs-builder changelog render` command checks the following path: `docs/changelog.yml`.
 You can specify a different path with the `--config` command option.
@@ -334,18 +334,19 @@ If you specify a file path with a different extension (not `.yml` or `.yaml`), t
 
 ## Create documentation [render-changelogs]
 
-The `docs-builder changelog render` command creates markdown files from changelog bundles for documentation purposes.
+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:
 
 ```sh
-Render bundled changelog(s) to markdown files
+Render bundled changelog(s) to markdown or asciidoc files
 
 Options:
   --input <string[]>             Required: Bundle input(s) in format "bundle-file-path|changelog-file-path|repo|link-visibility" (use pipe as delimiter). To merge multiple bundles, separate them with commas. Only bundle-file-path is required. link-visibility can be "hide-links" or "keep-links" (default). Paths must be absolute or use environment variables; tilde (~) expansion is not supported. [Required]
-  --output <string?>             Optional: Output directory for rendered markdown files. Defaults to current directory [Default: null]
-  --title <string?>              Optional: Title to use for section headers in output markdown files. Defaults to version from first bundle [Default: null]
+  --output <string?>             Optional: Output directory for rendered files. Defaults to current directory [Default: null]
+  --title <string?>              Optional: Title to use for section headers in output files. Defaults to version from first bundle [Default: null]
   --subsections                  Optional: Group entries by area/component in subsections. For breaking changes with a subtype, groups by subtype instead of area. Defaults to false
-  --hide-features <string[]?>    Filter by feature IDs (comma-separated), or a path to a newline-delimited file containing feature IDs. Can be specified multiple times. Entries with matching feature-id values will be commented out in the markdown output. [Default: null]
+  --hide-features <string[]?>    Filter by feature IDs (comma-separated), or a path to a newline-delimited file containing feature IDs. Can be specified multiple times. Entries with matching feature-id values will be commented out in the output. [Default: null]
+  --file-type <string>           Optional: Output file type. Valid values: "markdown" or "asciidoc". Defaults to "markdown" [Default: markdown]
   --config <string?>             Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml' [Default: null]
 ```
 
@@ -379,7 +380,7 @@ docs-builder changelog render \
 ```
 
 1. Provide information about the changelog bundle(s). The format for each bundle is `"<bundle-file-path>|<changelog-file-path>|<repository>|<link-visibility>"` using pipe (`|`) as delimiter. To merge multiple bundles, separate them with commas (`,`). Only the `<bundle-file-path>` is required for each bundle. The `<changelog-file-path>` is useful if the changelogs are not in the default directory and are not resolved within the bundle. The `<repository>` is necessary if your changelogs do not contain full URLs for the pull requests or issues. The `<link-visibility>` can be `hide-links` or `keep-links` (default) to control whether PR/issue links are hidden for entries from private repositories.
-2. The `--title` value is used for an output folder name and for section titles in the markdown files. If you omit `--title` and the first bundle contains a product `target` value, that value is used. Otherwise, if none of the bundles have product `target` fields, the title defaults to "unknown".
+2. The `--title` value is used for an output folder name and for section titles in the output files. If you omit `--title` and the first bundle contains a product `target` value, that value is used. Otherwise, if none of the bundles have product `target` fields, the title defaults to "unknown".
 3. By default the command creates the output files in the current directory.
 4. By default the changelog areas are not displayed in the output. Add `--subsections` to group changelog details by their `areas`. For breaking changes that have a `subtype` value, the subsections will be grouped by subtype instead of area.
 
@@ -408,3 +409,16 @@ To comment out the pull request and issue links, for example if they relate to a
 
 If you have changelogs with `feature-id` values and you want them to be omitted from the output, use the `--hide-features` option.
 For more information, refer to [](/cli/release/changelog-render.md).
+
+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 \ <1>
+  --subsections
+```
+
+1. Generate a single asciidoc file instead of multiple markdown files.

src/services/Elastic.Documentation.Services/Changelog/ChangelogRenderInput.cs

@@ -5,7 +5,7 @@
 namespace Elastic.Documentation.Services.Changelog;
 
 /// <summary>
-/// Input data for rendering changelog bundle to markdown
+/// Input data for rendering changelog bundle to markdown or asciidoc
 /// </summary>
 public class ChangelogRenderInput
 {
@@ -15,5 +15,6 @@ public class ChangelogRenderInput
 	public bool Subsections { get; set; }
 	public string[]? HideFeatures { get; set; }
 	public string? Config { get; set; }
+	public string FileType { get; set; } = "markdown";
 }