[Changelog] Fix missing links in changelog directive and render command#3228
Merged
[Changelog] Fix missing links in changelog directive and render command#3228
Conversation
Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # src/Elastic.Markdown/Myst/Directives/Changelog/ChangelogBlock.cs # src/Elastic.Markdown/Myst/Directives/Changelog/ChangelogInlineRenderer.cs
Adds the option row, details subsection, and updates the section-types table and record-descriptions note to reflect that separated types render as flattened bullets by default and require :dropdowns: to keep the previous expandable layout. Co-authored-by: Cursor <cursoragent@cursor.com>
cotti
approved these changes
May 4, 2026
Contributor
📝 WalkthroughWalkthroughThe PR adds a new Sequence Diagram(s)sequenceDiagram
participant User
participant ChangelogBlock
participant ChangelogInlineRenderer
participant ChangelogTextUtilities
participant FileSystem/Output
User->>ChangelogBlock: invoke {changelog} directive (options include :dropdowns:)
ChangelogBlock->>ChangelogBlock: parse options -> set DropdownsEnabled
ChangelogBlock->>ChangelogInlineRenderer: call RenderChangelogMarkdown(bundle, DropdownsEnabled, ...)
ChangelogInlineRenderer->>ChangelogInlineRenderer: RenderSingleBundle -> GenerateMarkdown
alt dropdownsEnabled == true
ChangelogInlineRenderer->>ChangelogInlineRenderer: RenderDetailedEntries (dropdown syntax)
else dropdownsEnabled == false
ChangelogInlineRenderer->>ChangelogInlineRenderer: RenderDetailedEntriesFlattened (bulleted layout)
end
ChangelogInlineRenderer->>ChangelogTextUtilities: HasVisibleLinks(entry, repo, hidePrivateLinks, owner)
ChangelogTextUtilities-->>ChangelogInlineRenderer: boolean (visible links?)
ChangelogInlineRenderer->>FileSystem/Output: write generated markdown/html files
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches✨ Simplify code
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/syntax/changelog.md (1)
123-145:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix the
#dropdownsfragment target.The new intra-page links point at
#dropdowns, but#### \:dropdowns:` [dropdowns]` does not create that fragment, and markdownlint is already flagging MD051 here. Those links will ship broken.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/syntax/changelog.md` around lines 123 - 145, The intra-page link target "#dropdowns" is missing because the heading "#### `:dropdowns:` [dropdowns]" does not generate that fragment (MD051); update the heading to supply an explicit fragment so links work — e.g. replace the heading "#### `:dropdowns:` [dropdowns]" with one that defines the anchor (such as "#### `:dropdowns:` {`#dropdowns`}" or add an explicit HTML anchor like "<a id=\"dropdowns\"></a>" immediately before the "#### `:dropdowns:`" heading) so the "#dropdowns" links resolve correctly.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/Elastic.Markdown/Myst/Directives/Changelog/ChangelogInlineRenderer.cs`:
- Around line 463-488: RenderDetailedEntriesFlattened currently groups entries
by subtype but never emits the subtype header when groupBySubtype is true,
causing different subtypes to be collapsed; update
RenderDetailedEntriesFlattened to write a subtype heading for each group before
iterating its entries (use the group's Key for the label) and then call
RenderDetailedEntryFlattened for each entry; reference the
RenderDetailedEntriesFlattened method and ensure the heading output format
matches other render paths (the same markup used elsewhere for subtype headings
or the helper used by RenderDetailedEntries) so flattened output preserves
subtype labels.
- Around line 490-523: RenderDetailedEntryFlattened currently prefixes
description/impact/action with only a single " " so embedded newlines break the
list; before appending entry.Description, entry.Impact and entry.Action (and
only when the corresponding checks pass, e.g. !hideEntryDescriptions and not
null/whitespace), call ChangelogTextUtilities.Indent(...) on each value to
produce a properly-indented multi-line block and append that result (instead of
the raw property) so every line keeps the bullet indentation; update the three
places that append those fields in RenderDetailedEntryFlattened to use the
indented text.
- Around line 525-552: GetLinksText is stripping out formatted links that begin
with '%' (commented-out links produced by
ChangelogTextUtilities.FormatPrLink/FormatIssueLink when hideLinks is true), so
the flattened renderer drops all PR/issue references; remove the StartsWith('%')
filter in GetLinksText (i.e., add non-empty formatted values to linksParts
regardless of a leading '%') so commented links are preserved in the output,
leaving HasVisibleLinks logic unchanged and ensuring linksParts and the final
$"[{string.Join(", ", linksParts)}]" continue to work.
---
Outside diff comments:
In `@docs/syntax/changelog.md`:
- Around line 123-145: The intra-page link target "#dropdowns" is missing
because the heading "#### `:dropdowns:` [dropdowns]" does not generate that
fragment (MD051); update the heading to supply an explicit fragment so links
work — e.g. replace the heading "#### `:dropdowns:` [dropdowns]" with one that
defines the anchor (such as "#### `:dropdowns:` {`#dropdowns`}" or add an explicit
HTML anchor like "<a id=\"dropdowns\"></a>" immediately before the "####
`:dropdowns:`" heading) so the "#dropdowns" links resolve correctly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 3373137b-a46d-452e-9c2f-e99a64ebd0a1
📒 Files selected for processing (9)
docs/syntax/changelog.mdsrc/Elastic.Documentation/ReleaseNotes/ChangelogTextUtilities.cssrc/Elastic.Markdown/Myst/Directives/Changelog/ChangelogBlock.cssrc/Elastic.Markdown/Myst/Directives/Changelog/ChangelogInlineRenderer.cstests/Elastic.Changelog.Tests/Changelogs/Render/PrivateLinkBugTests.cstests/Elastic.Documentation.Configuration.Tests/ReleaseNotes/ChangelogTextUtilitiesTests.cstests/Elastic.Markdown.Tests/Directives/ChangelogDropdownsTests.cstests/Elastic.Markdown.Tests/Directives/ChangelogHideLinksTests.cstests/Elastic.Markdown.Tests/Directives/ChangelogPrivateLinkBugTests.cs
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The changelog directive currently outputs incomplete phrases when the only links or issues are private (sanitized) links.
This would seem to be a regression due to changes in our method for sanitizing links, because I don't remember seeing this in earlier tests.
Expected behavior
If there are no public links, the phrase should be omitted.
Screenshots
Solution
AI implementation summary
Main Feature:
:dropdowns:Option for Changelog DirectiveProblem Solved: When using
:description-visibility: auto/hide-descriptions, separated types (breaking changes, deprecations, known issues, highlights) would render as empty clickable dropdown shells, creating poor UX.(Note, this problem occurs with or without that
description-visibilityoption, but there were enough dependencies to warrant stacking the PRs).Solution: Added a new
:dropdowns:directive option that controls rendering behavior for separated types.Key Changes
1. New Directive Option Implementation
src/Elastic.Markdown/Myst/Directives/Changelog/ChangelogBlock.csDropdownsEnabledproperty usingPropBool("dropdowns"):subsections:) where omission = false, presence = true:dropdowns:: Separated types render as Myst dropdown sections2. Rendering Logic Updates
src/Elastic.Markdown/Myst/Directives/Changelog/ChangelogInlineRenderer.csRenderDetailedEntriesFlattened()andRenderDetailedEntryFlattened()methods3. Private Links Bug Fix
src/Elastic.Documentation/ReleaseNotes/ChangelogTextUtilities.cs,ChangelogInlineRenderer.cs4. Comprehensive Test Coverage
tests/Elastic.Markdown.Tests/Directives/ChangelogDropdownsTests.cs:description-visibility:, and mixed type scenarios:dropdowns:and:description-visibility: keep-descriptionsto maintain backward compatibility inChangelogPrivateLinkBugTests.csandChangelogHideLinksTests.cs5. Bug Fixes
Behavior Summary
:dropdowns:):dropdowns:Breaking Change
:dropdowns:to maintain current behaviorFiles Modified
src/Elastic.Markdown/Myst/Directives/Changelog/ChangelogBlock.cssrc/Elastic.Markdown/Myst/Directives/Changelog/ChangelogInlineRenderer.cssrc/Elastic.Documentation/ReleaseNotes/ChangelogTextUtilities.cstests/Elastic.Markdown.Tests/Directives/ChangelogDropdownsTests.cs(new)tests/Elastic.Markdown.Tests/Directives/ChangelogPrivateLinkBugTests.cstests/Elastic.Markdown.Tests/Directives/ChangelogHideLinksTests.cstests/Elastic.Changelog.Tests/Changelogs/Render/PrivateLinkBugTests.cstests/Elastic.Documentation.Configuration.Tests/ReleaseNotes/ChangelogTextUtilitiesTests.csNote: Documentation update for
docs/syntax/changelog.mdstill pending to document the new:dropdowns:option.Testing
I verified that it works for pages that want dropdowns, for example, in a kibana
deprecations.mdfile like this::::{changelog} /releases/kibana :subsections: :type: deprecation :dropdowns: :descriptions-visibility: keep-descriptions :::It renders the same as current Kibana pages:
I also verified that it works for pages that don't want dropdowns, for example, in a private repo where we're using the default options (i.e. no
dropdownsordescriptions-visibilityset), it shows a nice plain bulleted list now:Ditto for breaking changes:
... and known issues:
I confirmed that the missing links no longer appear in the "changelog render" command output, though it means there are some empty dropdowns possible. This will be pursued in a follow-up PR.
Generative AI disclosure
Tool(s) and model(s) used: composer-2, claude-4-sonnet-thinking