Add changelog render --dropdowns

docs/cli/changelog/render.md

@@ -55,9 +55,16 @@ The `render` command automatically discovers and merges `.amend-*.yaml` files wi
 :   Defaults to false.
 :   When enabled, entries are grouped by their area within each section. The first area from each entry's areas list is used for grouping.
 
+`--dropdowns`
+:   Optional: Render separated types (breaking changes, deprecations, known issues, highlights) as MyST dropdowns.
+:   Defaults to false (flattened bulleted lists).
+:   When enabled, each entry in separated files is rendered as a collapsible dropdown section using MyST syntax (`::::{dropdown}`).
+:   When disabled (default), entries are rendered as flattened bulleted lists with PR/issue links inline and Impact/Action sections indented.
+:   This flag only affects markdown output; AsciiDoc output always uses its standard format.
+
 `--title <string?>`
 :   Optional: The title to use for section headers, directories, and anchors in output files.
-:   Defaults to the version in the first bundle.
+:   Defaults to the version in the first bundle. When omitted, ISO date targets are formatted for display the same way as the `{changelog}` directive (e.g., `2026-05-04` becomes "May 4, 2026", `2026-05` becomes "May 2026"), while directory names and heading anchors continue to use the raw target slug.
 :   If the string contains spaces, they are replaced with dashes when used in directory names and anchors.
 
 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 [](/contribute/publish-changelogs.md). For how the directive differs, see the [{changelog} directive syntax reference](/syntax/changelog.md).
@@ -91,6 +98,12 @@ When `--file-type asciidoc` is specified, the command generates a single asciido
 
 The asciidoc output uses attribute references for links (for example, `{repo-pull}NUMBER[#NUMBER]`).
 
+AsciiDoc output ignores the `--dropdowns` flag and always uses a standardized format with the following characteristics:
+
+- Multi-block entries (containing description, Impact, and Action sections) use proper list continuation markers (`+`) to maintain list structure
+- Strong text formatting uses idiomatic single asterisk syntax (`*Impact:*`, `*Action:*`) following AsciiDoc best practices
+- All content blocks are properly attached to their parent list items for correct rendering
+
 ### 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:
@@ -141,3 +154,21 @@ docs-builder changelog render \
   --input "./public-bundle.yaml|./changelog|elasticsearch|keep-links,./private-bundle.yaml|./private-changelog|internal-repo|hide-links" \
   --output ./release-notes
 ```
+
+### Render with dropdown format
+
+```sh
+docs-builder changelog render \
+  --input "./bundles/9.3.0.yaml|./changelog|elasticsearch" \
+  --dropdowns \
+  --output ./release-notes
+```
+
+### Render with subsections and flattened format (default)
+
+```sh
+docs-builder changelog render \
+  --input "./bundles/9.3.0.yaml|./changelog|elasticsearch" \
+  --subsections \
+  --output ./release-notes
+```

src/services/Elastic.Changelog/Rendering/Asciidoc/AsciidocRendererBase.cs

@@ -61,40 +61,48 @@ private static void RenderEntryTitleAndLinks(StringBuilder sb, ChangelogEntry en
 	}
 
 	/// <summary>
-	/// Renders an entry's description with optional comment handling
+	/// Renders an entry's description with optional comment handling and list continuation
 	/// </summary>
-	private static void RenderEntryDescription(StringBuilder sb, ChangelogEntry entry, bool shouldHide)
+	private static void RenderEntryDescription(StringBuilder sb, ChangelogEntry entry, bool shouldHide, bool needsContinuation = true)
 	{
 		if (string.IsNullOrWhiteSpace(entry.Description))
 			return;
 
 		_ = sb.AppendLine();
-		var indented = ChangelogTextUtilities.Indent(entry.Description);
+
+		// Add list continuation marker for multi-block list items
+		if (needsContinuation)
+		{
+			_ = sb.AppendLine("+");
+		}
+
 		if (shouldHide)
 		{
-			var indentedLines = indented.Split('\n');
-			foreach (var line in indentedLines)
+			var descriptionLines = entry.Description.Split('\n');
+			foreach (var line in descriptionLines)
 				_ = sb.AppendLine(CultureInfo.InvariantCulture, $"// {line}");
 		}
 		else
-			_ = sb.AppendLine(indented);
+			_ = sb.AppendLine(entry.Description);
 	}
 
 	/// <summary>
-	/// Renders Impact and Action fields for breaking changes, deprecations, and known issues
+	/// Renders Impact and Action fields for breaking changes, deprecations, and known issues with list continuation
 	/// </summary>
 	private static void RenderImpactAndAction(StringBuilder sb, ChangelogEntry entry)
 	{
 		if (!string.IsNullOrWhiteSpace(entry.Impact))
 		{
 			_ = sb.AppendLine();
-			_ = sb.AppendLine(CultureInfo.InvariantCulture, $"**Impact:** {entry.Impact}");
+			_ = sb.AppendLine("+");
+			_ = sb.AppendLine(CultureInfo.InvariantCulture, $"*Impact:* {entry.Impact}");
 		}
 
 		if (!string.IsNullOrWhiteSpace(entry.Action))
 		{
 			_ = sb.AppendLine();
-			_ = sb.AppendLine(CultureInfo.InvariantCulture, $"**Action:** {entry.Action}");
+			_ = sb.AppendLine("+");
+			_ = sb.AppendLine(CultureInfo.InvariantCulture, $"*Action:* {entry.Action}");
 		}
 	}
 
@@ -105,7 +113,7 @@ protected void RenderBasicEntry(StringBuilder sb, ChangelogEntry entry, Changelo
 	{
 		var (entryRepo, _, hideLinks, shouldHide) = ChangelogRenderUtilities.GetEntryContext(entry, context);
 		RenderEntryTitleAndLinks(sb, entry, entryRepo, hideLinks, shouldHide);
-		RenderEntryDescription(sb, entry, shouldHide);
+		RenderEntryDescription(sb, entry, shouldHide, needsContinuation: !string.IsNullOrWhiteSpace(entry.Description));
 		_ = sb.AppendLine();
 	}
 
@@ -116,7 +124,11 @@ protected void RenderEntryWithImpactAction(StringBuilder sb, ChangelogEntry entr
 	{
 		var (entryRepo, _, hideLinks, shouldHide) = ChangelogRenderUtilities.GetEntryContext(entry, context);
 		RenderEntryTitleAndLinks(sb, entry, entryRepo, hideLinks, shouldHide);
-		RenderEntryDescription(sb, entry, shouldHide);
+
+		// Description needs continuation when it exists
+		var hasDescription = !string.IsNullOrWhiteSpace(entry.Description);
+		RenderEntryDescription(sb, entry, shouldHide, needsContinuation: hasDescription);
+
 		RenderImpactAndAction(sb, entry);
 		_ = sb.AppendLine();
 	}

src/services/Elastic.Changelog/Rendering/Asciidoc/BreakingChangesAsciidocRenderer.cs

@@ -2,6 +2,7 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+using System.Globalization;
 using System.Text;
 using Elastic.Documentation;
 using Elastic.Documentation.ReleaseNotes;
@@ -30,8 +31,17 @@ public override void Render(IReadOnlyCollection<ChangelogEntry> entries, Changel
 			if (context.Subsections && !string.IsNullOrWhiteSpace(group.Key))
 			{
 				var header = ChangelogTextUtilities.FormatSubtypeHeader(group.Key);
-				var headerLine = allEntriesHidden ? $"// **{header}**" : $"**{header}**";
-				_ = sb.AppendLine(headerLine);
+
+				if (allEntriesHidden)
+				{
+					_ = sb.AppendLine("// [float]");
+					_ = sb.AppendLine(CultureInfo.InvariantCulture, $"// ==== {header}");
+				}
+				else
+				{
+					_ = sb.AppendLine("[float]");
+					_ = sb.AppendLine(CultureInfo.InvariantCulture, $"==== {header}");
+				}
 				_ = sb.AppendLine();
 			}
 

src/services/Elastic.Changelog/Rendering/Asciidoc/DeprecationsAsciidocRenderer.cs

@@ -2,6 +2,7 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+using System.Globalization;
 using System.Text;
 using Elastic.Documentation.ReleaseNotes;
 
@@ -15,22 +16,39 @@ public class DeprecationsAsciidocRenderer(StringBuilder sb) : AsciidocRendererBa
 	/// <inheritdoc />
 	public override void Render(IReadOnlyCollection<ChangelogEntry> entries, ChangelogRenderContext context)
 	{
-		var groupedByArea = entries.GroupBy(e => ChangelogRenderUtilities.GetComponent(e, context)).OrderBy(g => g.Key).ToList();
+		// Group by area if subsections is enabled, otherwise use single group
+		if (entries.Count == 0)
+			return;
+		var groupedEntries = context.Subsections
+			? entries.GroupBy(e => ChangelogRenderUtilities.GetComponent(e, context)).OrderBy(g => g.Key).ToList()
+			: [entries.GroupBy(_ => string.Empty).First()];
 
-		foreach (var areaGroup in groupedByArea)
+		foreach (var group in groupedEntries)
 		{
-			// Check if all entries in this area group are hidden
-			var allEntriesHidden = areaGroup.All(entry =>
+			// Check if all entries in this group are hidden
+			var allEntriesHidden = group.All(entry =>
 				ChangelogRenderUtilities.ShouldHideEntry(entry, context.FeatureIdsToHide, context));
 
-			var componentName = !string.IsNullOrWhiteSpace(areaGroup.Key) ? areaGroup.Key : "General";
-			var formattedComponent = ChangelogTextUtilities.FormatAreaHeader(componentName);
+			// Add nested section header when subsections are enabled and group has a name
+			if (context.Subsections && !string.IsNullOrWhiteSpace(group.Key))
+			{
+				var componentName = group.Key != string.Empty ? group.Key : "General";
+				var formattedComponent = ChangelogTextUtilities.FormatAreaHeader(componentName);
 
-			var headerLine = allEntriesHidden ? $"// {formattedComponent}::" : $"{formattedComponent}::";
-			_ = sb.AppendLine(headerLine);
-			_ = sb.AppendLine();
+				if (allEntriesHidden)
+				{
+					_ = sb.AppendLine("// [float]");
+					_ = sb.AppendLine(CultureInfo.InvariantCulture, $"// ==== {formattedComponent}");
+				}
+				else
+				{
+					_ = sb.AppendLine("[float]");
+					_ = sb.AppendLine(CultureInfo.InvariantCulture, $"==== {formattedComponent}");
+				}
+				_ = sb.AppendLine();
+			}
 
-			foreach (var entry in areaGroup)
+			foreach (var entry in group)
 				RenderEntryWithImpactAction(sb, entry, context);
 		}
 	}

src/services/Elastic.Changelog/Rendering/Asciidoc/EntriesByAreaAsciidocRenderer.cs

@@ -2,6 +2,7 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+using System.Globalization;
 using System.Text;
 using Elastic.Documentation.ReleaseNotes;
 
@@ -15,24 +16,37 @@ public class EntriesByAreaAsciidocRenderer(StringBuilder sb) : AsciidocRendererB
 	/// <inheritdoc />
 	public override void Render(IReadOnlyCollection<ChangelogEntry> entries, ChangelogRenderContext context)
 	{
-		var groupedByArea = context.Subsections
+		// Group by area if subsections is enabled, otherwise use single group
+		var groupedEntries = context.Subsections
 			? entries.GroupBy(e => ChangelogRenderUtilities.GetComponent(e, context)).OrderBy(g => g.Key).ToList()
-			: entries.GroupBy(e => ChangelogRenderUtilities.GetComponent(e, context)).ToList();
+			: [entries.GroupBy(_ => string.Empty).First()];
 
-		foreach (var areaGroup in groupedByArea)
+		foreach (var group in groupedEntries)
 		{
-			// Check if all entries in this area group are hidden
-			var allEntriesHidden = areaGroup.All(entry =>
+			// Check if all entries in this group are hidden
+			var allEntriesHidden = group.All(entry =>
 				ChangelogRenderUtilities.ShouldHideEntry(entry, context.FeatureIdsToHide, context));
 
-			var componentName = !string.IsNullOrWhiteSpace(areaGroup.Key) ? areaGroup.Key : "General";
-			var formattedComponent = ChangelogTextUtilities.FormatAreaHeader(componentName);
+			// Add nested section header when subsections are enabled and group has a name
+			if (context.Subsections && !string.IsNullOrWhiteSpace(group.Key))
+			{
+				var componentName = group.Key != string.Empty ? group.Key : "General";
+				var formattedComponent = ChangelogTextUtilities.FormatAreaHeader(componentName);
 
-			var headerLine = allEntriesHidden ? $"// {formattedComponent}::" : $"{formattedComponent}::";
-			_ = sb.AppendLine(headerLine);
-			_ = sb.AppendLine();
+				if (allEntriesHidden)
+				{
+					_ = sb.AppendLine("// [float]");
+					_ = sb.AppendLine(CultureInfo.InvariantCulture, $"// ==== {formattedComponent}");
+				}
+				else
+				{
+					_ = sb.AppendLine("[float]");
+					_ = sb.AppendLine(CultureInfo.InvariantCulture, $"==== {formattedComponent}");
+				}
+				_ = sb.AppendLine();
+			}
 
-			foreach (var entry in areaGroup)
+			foreach (var entry in group)
 				RenderBasicEntry(sb, entry, context);
 		}
 	}

src/services/Elastic.Changelog/Rendering/Asciidoc/HighlightsAsciidocRenderer.cs

@@ -2,6 +2,7 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+using System.Globalization;
 using System.Text;
 using Elastic.Documentation.ReleaseNotes;
 
@@ -15,24 +16,37 @@ public class HighlightsAsciidocRenderer(StringBuilder sb) : AsciidocRendererBase
 	/// <inheritdoc />
 	public override void Render(IReadOnlyCollection<ChangelogEntry> entries, ChangelogRenderContext context)
 	{
-		var groupedByArea = context.Subsections
+		// Group by area if subsections is enabled, otherwise use single group
+		var groupedEntries = context.Subsections
 			? entries.GroupBy(e => ChangelogRenderUtilities.GetComponent(e, context)).OrderBy(g => g.Key).ToList()
-			: entries.GroupBy(e => ChangelogRenderUtilities.GetComponent(e, context)).ToList();
+			: [entries.GroupBy(_ => string.Empty).First()];
 
-		foreach (var areaGroup in groupedByArea)
+		foreach (var group in groupedEntries)
 		{
-			// Check if all entries in this area group are hidden
-			var allEntriesHidden = areaGroup.All(entry =>
+			// Check if all entries in this group are hidden
+			var allEntriesHidden = group.All(entry =>
 				ChangelogRenderUtilities.ShouldHideEntry(entry, context.FeatureIdsToHide, context));
 
-			var componentName = !string.IsNullOrWhiteSpace(areaGroup.Key) ? areaGroup.Key : "General";
-			var formattedComponent = ChangelogTextUtilities.FormatAreaHeader(componentName);
+			// Add nested section header when subsections are enabled and group has a name
+			if (context.Subsections && !string.IsNullOrWhiteSpace(group.Key))
+			{
+				var componentName = group.Key != string.Empty ? group.Key : "General";
+				var formattedComponent = ChangelogTextUtilities.FormatAreaHeader(componentName);
 
-			var headerLine = allEntriesHidden ? $"// {formattedComponent}::" : $"{formattedComponent}::";
-			_ = sb.AppendLine(headerLine);
-			_ = sb.AppendLine();
+				if (allEntriesHidden)
+				{
+					_ = sb.AppendLine("// [float]");
+					_ = sb.AppendLine(CultureInfo.InvariantCulture, $"// ==== {formattedComponent}");
+				}
+				else
+				{
+					_ = sb.AppendLine("[float]");
+					_ = sb.AppendLine(CultureInfo.InvariantCulture, $"==== {formattedComponent}");
+				}
+				_ = sb.AppendLine();
+			}
 
-			foreach (var entry in areaGroup)
+			foreach (var entry in group)
 				RenderBasicEntry(sb, entry, context);
 		}
 	}

src/services/Elastic.Changelog/Rendering/Asciidoc/KnownIssuesAsciidocRenderer.cs

@@ -2,6 +2,7 @@
 // Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
 // See the LICENSE file in the project root for more information
 
+using System.Globalization;
 using System.Text;
 using Elastic.Documentation.ReleaseNotes;
 
@@ -15,22 +16,37 @@ public class KnownIssuesAsciidocRenderer(StringBuilder sb) : AsciidocRendererBas
 	/// <inheritdoc />
 	public override void Render(IReadOnlyCollection<ChangelogEntry> entries, ChangelogRenderContext context)
 	{
-		var groupedByArea = entries.GroupBy(e => ChangelogRenderUtilities.GetComponent(e, context)).OrderBy(g => g.Key).ToList();
+		// Group by area if subsections is enabled, otherwise use single group
+		var groupedEntries = context.Subsections
+			? entries.GroupBy(e => ChangelogRenderUtilities.GetComponent(e, context)).OrderBy(g => g.Key).ToList()
+			: [entries.GroupBy(_ => string.Empty).First()];
 
-		foreach (var areaGroup in groupedByArea)
+		foreach (var group in groupedEntries)
 		{
-			// Check if all entries in this area group are hidden
-			var allEntriesHidden = areaGroup.All(entry =>
+			// Check if all entries in this group are hidden
+			var allEntriesHidden = group.All(entry =>
 				ChangelogRenderUtilities.ShouldHideEntry(entry, context.FeatureIdsToHide, context));
 
-			var componentName = !string.IsNullOrWhiteSpace(areaGroup.Key) ? areaGroup.Key : "General";
-			var formattedComponent = ChangelogTextUtilities.FormatAreaHeader(componentName);
+			// Add nested section header when subsections are enabled and group has a name
+			if (context.Subsections && !string.IsNullOrWhiteSpace(group.Key))
+			{
+				var componentName = group.Key != string.Empty ? group.Key : "General";
+				var formattedComponent = ChangelogTextUtilities.FormatAreaHeader(componentName);
 
-			var headerLine = allEntriesHidden ? $"// {formattedComponent}::" : $"{formattedComponent}::";
-			_ = sb.AppendLine(headerLine);
-			_ = sb.AppendLine();
+				if (allEntriesHidden)
+				{
+					_ = sb.AppendLine("// [float]");
+					_ = sb.AppendLine(CultureInfo.InvariantCulture, $"// ==== {formattedComponent}");
+				}
+				else
+				{
+					_ = sb.AppendLine("[float]");
+					_ = sb.AppendLine(CultureInfo.InvariantCulture, $"==== {formattedComponent}");
+				}
+				_ = sb.AppendLine();
+			}
 
-			foreach (var entry in areaGroup)
+			foreach (var entry in group)
 				RenderEntryWithImpactAction(sb, entry, context);
 		}
 	}

src/services/Elastic.Changelog/Rendering/ChangelogRenderContext.cs

@@ -20,6 +20,7 @@ public record ChangelogRenderContext
 	public required string Owner { get; init; }
 	public required IReadOnlyDictionary<ChangelogEntryType, IReadOnlyCollection<ChangelogEntry>> EntriesByType { get; init; }
 	public required bool Subsections { get; init; }
+	public required bool Dropdowns { get; init; }
 	public required HashSet<string> FeatureIdsToHide { get; init; }
 	public required Dictionary<ChangelogEntry, HashSet<string>> EntryToBundleProducts { get; init; }
 	public required Dictionary<ChangelogEntry, string> EntryToRepo { get; init; }