Skip to content

Improve changelog render for asciidoc #3262

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cotti merged 2 commits into from
May 7, 2026
Merged

Improve changelog render for asciidoc #3262

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
628d2f6
Improve changelog render asciidoc output
lcawl May 7, 2026
975b420
Remove definition lists in favour of subsections
lcawl May 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/cli/changelog/render.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,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:
Expand Down
34 changes: 23 additions & 11 deletions src/services/Elastic.Changelog/Rendering/Asciidoc/AsciidocRendererBase.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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}");
}
}

Expand All @@ -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();
}

Expand All @@ -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();
}
Expand Down
14 changes: 12 additions & 2 deletions src/services/Elastic.Changelog/Rendering/Asciidoc/BreakingChangesAsciidocRenderer.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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();
}

Expand Down
36 changes: 26 additions & 10 deletions src/services/Elastic.Changelog/Rendering/Asciidoc/DeprecationsAsciidocRenderer.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand All @@ -15,22 +16,37 @@ 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
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);
}
}
Expand Down
36 changes: 25 additions & 11 deletions src/services/Elastic.Changelog/Rendering/Asciidoc/EntriesByAreaAsciidocRenderer.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand All @@ -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);
}
}
Expand Down
36 changes: 25 additions & 11 deletions src/services/Elastic.Changelog/Rendering/Asciidoc/HighlightsAsciidocRenderer.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand All @@ -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);
}
}
Expand Down
36 changes: 26 additions & 10 deletions src/services/Elastic.Changelog/Rendering/Asciidoc/KnownIssuesAsciidocRenderer.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand All @@ -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);
}
}
Expand Down
4 changes: 2 additions & 2 deletions src/services/Elastic.Changelog/Rendering/Markdown/BreakingChangesMarkdownRenderer.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ public override async Task RenderAsync(ChangelogRenderContext context, Cancel ct
_ = sb.AppendLine(InvariantCulture, $"::::{{dropdown}} {ChangelogTextUtilities.Beautify(entry.Title)}");
_ = sb.AppendLine(entry.Description ?? "% Describe the functionality that changed");
_ = sb.AppendLine();
RenderPrIssueLinks(sb, entry, entryRepo, entryOwner, entryHideLinks);
RenderPrIssueLinks(sb, new PrIssueLinkOptions(entry, entryRepo, entryOwner, entryHideLinks));

_ = sb.AppendLine(!string.IsNullOrWhiteSpace(entry.Impact)
? "**Impact**<br>" + entry.Impact
Expand Down Expand Up @@ -99,7 +99,7 @@ public override async Task RenderAsync(ChangelogRenderContext context, Cancel ct
}

// PR/Issue links with "For more information" pattern - indented for list continuation
RenderPrIssueLinks(sb, entry, entryRepo, entryOwner, entryHideLinks, indentForListItem: true);
RenderPrIssueLinks(sb, new PrIssueLinkOptions(entry, entryRepo, entryOwner, entryHideLinks, IndentForListItem: true));

// Impact and Action sections - indented for list continuation
if (!string.IsNullOrWhiteSpace(entry.Impact))
Expand Down
4 changes: 2 additions & 2 deletions src/services/Elastic.Changelog/Rendering/Markdown/DeprecationsMarkdownRenderer.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ public override async Task RenderAsync(ChangelogRenderContext context, Cancel ct
_ = sb.AppendLine(InvariantCulture, $"::::{{dropdown}} {ChangelogTextUtilities.Beautify(entry.Title)}");
_ = sb.AppendLine(entry.Description ?? "% Describe the functionality that was deprecated");
_ = sb.AppendLine();
RenderPrIssueLinks(sb, entry, entryRepo, entryOwner, entryHideLinks);
RenderPrIssueLinks(sb, new PrIssueLinkOptions(entry, entryRepo, entryOwner, entryHideLinks));

_ = sb.AppendLine(!string.IsNullOrWhiteSpace(entry.Impact)
? "**Impact**<br>" + entry.Impact
Expand Down Expand Up @@ -96,7 +96,7 @@ public override async Task RenderAsync(ChangelogRenderContext context, Cancel ct
}

// PR/Issue links with "For more information" pattern - indented for list continuation
RenderPrIssueLinks(sb, entry, entryRepo, entryOwner, entryHideLinks, indentForListItem: true);
RenderPrIssueLinks(sb, new PrIssueLinkOptions(entry, entryRepo, entryOwner, entryHideLinks, IndentForListItem: true));

// Impact and Action sections - indented for list continuation
if (!string.IsNullOrWhiteSpace(entry.Impact))
Expand Down
Loading
Loading