Add changelog highlights (#2643)

Co-authored-by: Felipe Cotti <felipe.cotti@elastic.co>
Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

Author: 3 people

docs/_docset.yml

@@ -227,6 +227,10 @@ toc:
       - folder: release-notes
         children:
           - file: index.md
+          - file: highlights.md
           - file: breaking-changes.md
           - file: deprecations.md
-          - file: known-issues.md
+          - file: known-issues.md
+      - folder: release-notes-all
+        children:
+          - file: index.md

docs/changelog/bundles/0.100.0.yaml

@@ -11,6 +11,7 @@ entries:
     areas:
       - CLI
     pr: https://github.com/elastic/docs-builder/pull/2350
+    highlight: true
     description: |
       Adds support for configuring PR labels that block changelog creation.
       This allows teams to mark PRs that should not generate changelog entries

docs/cli/release/changelog-render.md

@@ -72,13 +72,15 @@ When `--file-type markdown` is specified (the default), the command generates mu
 - `breaking-changes.md` - Contains breaking changes
 - `deprecations.md` - Contains deprecations
 - `known-issues.md` - Contains known issues
+- `highlights.md` - Contains highlighted entries (only created when at least one entry has `highlight: true`)
 
 ### Asciidoc format
 
 When `--file-type asciidoc` is specified, the command generates a single asciidoc file with all sections:
 
 - Security updates
 - Bug fixes
+- Highlights (only included when at least one entry has `highlight: true`)
 - New features and enhancements
 - Breaking changes
 - Deprecations

docs/contribute/changelog.md

@@ -625,3 +625,28 @@ docs-builder changelog render \
 ```
 
 1. Generate a single asciidoc file instead of multiple markdown files.
+
+#### Release highlights
+
+The `highlight` field allows you to mark changelog entries that should appear in a dedicated highlights page. Highlights are most commonly used for major or minor version releases to draw attention to the most important changes.
+
+When you set `highlight: true` on a changelog entry:
+
+- The entry appears in both the highlights page (`highlights.md`) and its normal type section (e.g., "Features and enhancements")
+- The highlights page is only created when at least one entry has `highlight: true` (unlike other special pages like `known-issues.md` which are always created)
+- Highlights can be any type of changelog entry (features, enhancements, bug fixes, etc.)
+
+Example changelog entry with highlight:
+
+```yaml
+type: feature
+products:
+- product: elasticsearch
+  target: 9.3.0
+  lifecycle: ga
+title: New Cloud Connect UI for self-managed installations
+description: Adds Cloud Connect functionality to Kibana, which allows you to use cloud solutions like AutoOps and Elastic Inference Service in your self-managed Elasticsearch clusters.
+highlight: true
+```
+
+When rendering changelogs, entries with `highlight: true` are collected from all types and rendered in a dedicated highlights section. In markdown output, this creates a separate `highlights.md` file. In asciidoc output, highlights appear as a dedicated section in the single asciidoc file.

docs/syntax/changelog.md

@@ -41,15 +41,16 @@ The directive supports the following options:
 
 #### `:type:`
 
-Controls which entry types are displayed. By default, the directive excludes "separated types" (known issues, breaking changes, and deprecations) which are typically shown on their own dedicated pages.
+Controls which entry types are displayed. By default, the directive excludes "separated types" (known issues, breaking changes, deprecations, and highlights) which are typically shown on their own dedicated pages.
 
 | Value | Description |
 |-------|-------------|
-| (omitted) | Default: shows all types EXCEPT known issues, breaking changes, and deprecations |
-| `all` | Shows all entry types including known issues, breaking changes, and deprecations |
+| (omitted) | Default: shows all types EXCEPT known issues, breaking changes, deprecations, and highlights |
+| `all` | Shows all entry types including known issues, breaking changes, deprecations, and highlights |
 | `breaking-change` | Shows only breaking change entries |
 | `deprecation` | Shows only deprecation entries |
 | `known-issue` | Shows only known issue entries |
+| `highlight` | Shows only highlighted entries |
 
 This allows you to create separate pages for different entry types:
 
@@ -84,6 +85,14 @@ This allows you to create separate pages for different entry types:
 :::
 ```
 
+```markdown
+# Highlights
+
+:::{changelog}
+:type: highlight
+:::
+```
+
 To show all entries on a single page (previous default behavior):
 
 ```markdown
@@ -379,9 +388,16 @@ Each bundle renders as a `## {version}` section with subsections beneath:
 | Regressions | `regression` | Grouped by area |
 | Other changes | `other` | Grouped by area |
 | Breaking changes | `breaking-change` | Expandable dropdowns |
+| Highlights | Entries with `highlight: true` | Expandable dropdowns |
 | Deprecations | `deprecation` | Expandable dropdowns |
 | Known issues | `known-issue` | Expandable dropdowns |
 
+**Note about highlights:**
+- Highlights only appear when using `:type: all` (they are excluded from the default view)
+- When rendered, highlighted entries appear in BOTH the "Highlights" section AND their original type section (for example, a highlighted feature appears in both "Highlights" and "Features and enhancements")
+- The "Highlights" section is only created when at least one entry has `highlight: true`
+- When using `:type: highlight`, only highlighted entries are shown (no section headers or other content)
+
 Sections with no entries of that type are omitted from the output.
 
 ## Example

docs/testing/release-notes-all/index.md

@@ -0,0 +1,5 @@
+# Release Notes (All)
+
+:::{changelog}
+:type: all
+:::

docs/testing/release-notes/highlights.md

@@ -0,0 +1,5 @@
+# Highlights
+
+:::{changelog}
+:type: highlight
+:::

src/Elastic.Markdown/Myst/Directives/Changelog/ChangelogBlock.cs

@@ -40,7 +40,12 @@ public enum ChangelogTypeFilter
 	/// <summary>
 	/// Show only known issue entries.
 	/// </summary>
-	KnownIssue
+	KnownIssue,
+
+	/// <summary>
+	/// Show only highlighted entries (where highlight == true).
+	/// </summary>
+	Highlight
 }
 
 /// <summary>
@@ -177,7 +182,7 @@ public override void FinalizeAndValidate(ParserContext context)
 
 	/// <summary>
 	/// Parses and validates the :type: option.
-	/// Valid values: all, breaking-change, deprecation, known-issue.
+	/// Valid values: all, breaking-change, deprecation, known-issue, highlight.
 	/// If not specified, returns Default (excludes separated types).
 	/// </summary>
 	private ChangelogTypeFilter ParseTypeFilter()
@@ -192,13 +197,14 @@ private ChangelogTypeFilter ParseTypeFilter()
 			"breaking-change" => ChangelogTypeFilter.BreakingChange,
 			"deprecation" => ChangelogTypeFilter.Deprecation,
 			"known-issue" => ChangelogTypeFilter.KnownIssue,
+			"highlight" => ChangelogTypeFilter.Highlight,
 			_ => EmitInvalidTypeFilterWarning(typeValue)
 		};
 	}
 
 	private ChangelogTypeFilter EmitInvalidTypeFilterWarning(string typeValue)
 	{
-		this.EmitWarning($"Invalid :type: value '{typeValue}'. Valid values are: all, breaking-change, deprecation, known-issue. Using default behavior.");
+		this.EmitWarning($"Invalid :type: value '{typeValue}'. Valid values are: all, breaking-change, deprecation, known-issue, highlight. Using default behavior.");
 		return ChangelogTypeFilter.Default;
 	}
 
@@ -456,6 +462,20 @@ private IEnumerable<PageTocItem> ComputeTableOfContent()
 					Level = 3
 				};
 
+			// Check for highlights (any entry with highlight == true) - only show in :type: all
+			var hasHighlights = bundle.Entries.Any(e => e.Highlight == true);
+			if (hasHighlights && TypeFilter == ChangelogTypeFilter.All)
+				yield return new PageTocItem
+				{
+					Heading = "Highlights",
+					Slug = $"{repo}-{titleSlug}-highlights",
+					Level = 3
+				};
+
+			// When filtering by highlight, skip all other type-based sections
+			if (TypeFilter == ChangelogTypeFilter.Highlight)
+				continue;
+
 			if (shouldInclude(ChangelogEntryType.Security) && entriesByType.ContainsKey(ChangelogEntryType.Security))
 				yield return new PageTocItem
 				{

src/Elastic.Markdown/Myst/Directives/Changelog/ChangelogInlineRenderer.cs

@@ -87,6 +87,7 @@ private static IReadOnlyList<ChangelogEntry> FilterEntriesByType(
 			ChangelogTypeFilter.BreakingChange => entries.Where(e => e.Type == ChangelogEntryType.BreakingChange).ToList(),
 			ChangelogTypeFilter.Deprecation => entries.Where(e => e.Type == ChangelogEntryType.Deprecation).ToList(),
 			ChangelogTypeFilter.KnownIssue => entries.Where(e => e.Type == ChangelogEntryType.KnownIssue).ToList(),
+			ChangelogTypeFilter.Highlight => entries.Where(e => e.Highlight == true).ToList(),
 			_ => entries.Where(e => !ChangelogBlock.SeparatedTypes.Contains(e.Type)).ToList() // Default: exclude separated types
 		};
 
@@ -159,26 +160,48 @@ private static string GenerateMarkdown(
 		var deprecations = entriesByType.GetValueOrDefault(ChangelogEntryType.Deprecation, []);
 		var knownIssues = entriesByType.GetValueOrDefault(ChangelogEntryType.KnownIssue, []);
 
+		// Get highlighted entries from all types
+		var highlights = entriesByType.Values
+			.SelectMany(e => e)
+			.Where(e => e.Highlight == true)
+			.ToList();
+
 		_ = sb.AppendLine(CultureInfo.InvariantCulture, $"## {title}");
 
 		// Check if we have any content at all
 		var hasAnyContent = features.Count > 0 || enhancements.Count > 0 || security.Count > 0 ||
 							bugFixes.Count > 0 || docs.Count > 0 || regressions.Count > 0 || other.Count > 0 ||
-							breakingChanges.Count > 0 || deprecations.Count > 0 || knownIssues.Count > 0;
+							breakingChanges.Count > 0 || deprecations.Count > 0 || knownIssues.Count > 0 ||
+							highlights.Count > 0;
 
 		if (!hasAnyContent)
 		{
 			_ = sb.AppendLine(GetEmptyMessage(typeFilter));
 			return sb.ToString();
 		}
 
+		// Special case: When filtering by highlight, render only highlights without type-based sections
+		if (typeFilter == ChangelogTypeFilter.Highlight)
+		{
+			if (highlights.Count > 0)
+				RenderDetailedEntries(sb, highlights, repo, groupBySubtype: false, hideLinks);
+			return sb.ToString();
+		}
+
 		if (breakingChanges.Count > 0)
 		{
 			_ = sb.AppendLine();
 			_ = sb.AppendLine(CultureInfo.InvariantCulture, $"### Breaking changes [{repo}-{titleSlug}-breaking-changes]");
 			RenderDetailedEntries(sb, breakingChanges, repo, groupBySubtype: true, hideLinks);
 		}
 
+		if (highlights.Count > 0 && typeFilter == ChangelogTypeFilter.All)
+		{
+			_ = sb.AppendLine();
+			_ = sb.AppendLine(CultureInfo.InvariantCulture, $"### Highlights [{repo}-{titleSlug}-highlights]");
+			RenderDetailedEntries(sb, highlights, repo, groupBySubtype: false, hideLinks);
+		}
+
 		if (security.Count > 0)
 		{
 			_ = sb.AppendLine();

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

@@ -25,6 +25,7 @@ public async Task RenderAsciidoc(ChangelogRenderContext context, Cancel ctx)
 		var breakingChangesRenderer = new BreakingChangesAsciidocRenderer(sb);
 		var deprecationsRenderer = new DeprecationsAsciidocRenderer(sb);
 		var knownIssuesRenderer = new KnownIssuesAsciidocRenderer(sb);
+		var highlightsRenderer = new HighlightsAsciidocRenderer(sb);
 
 		// Add anchor
 		_ = sb.AppendLine(InvariantCulture, $"[[release-notes-{context.TitleSlug}]]");
@@ -60,6 +61,18 @@ public async Task RenderAsciidoc(ChangelogRenderContext context, Cancel ctx)
 			_ = sb.AppendLine();
 		}
 
+		// Render highlights (only if any entries have highlight == true)
+		var highlights = entriesByType.Values
+			.SelectMany(e => e)
+			.Where(e => e.Highlight == true)
+			.ToList();
+		if (highlights.Count > 0)
+		{
+			RenderSectionHeader(sb, "highlights", context.TitleSlug, "Highlights");
+			highlightsRenderer.Render(highlights, context);
+			_ = sb.AppendLine();
+		}
+
 		// Render features and enhancements
 		if (features.Count > 0 || enhancements.Count > 0)
 		{