feat(cli-docs): supplemental content system for generated CLI reference pages#3271
Merged
Conversation
…, and assembler/changelog content
Adds four generator improvements and restores hand-authored content for the
assembler and changelog namespaces.
Generator changes:
- New `:::{cli-modifiers}` directive renders a pill row (destructive,
requires-confirmation, auth required, idempotent, scope, streaming,
long-running) between the usage block and description on generated pages
- `CliSupplementalDoc` parser splits supplemental files into typed sections:
`## Description` overrides the intro; `## Options` / `## Arguments` override
per-parameter text (unknown keys are a build error); any other `##` heading
appends as post-content after the generated parameter table
- `__argh_root` and other `ReservedMetaCommands` tokens are stripped from
generated usage lines
- Schema `notes` field is no longer rendered (use supplemental post-content instead)
- Behaviour-flag params (dryRun, confirmationSkip, output) get a quick-reference
block above Arguments/Options
- Stack-overflow fix: expose `Collector` as `protected` on `MarkdownFile` so CLI
file subclasses can emit diagnostics without storing `BuildContext` as a record field
Supplemental content:
- Assembler namespace and all sub-commands (assemble, build, clone, serve, index,
bloom-filter create/lookup, config init, content-source match/validate,
deploy apply/plan/update-redirects, navigation validate/validate-link-reference)
- Changelog commands: add, bundle-amend, evaluate-pr, gh-release, init, remove, render
Docs:
- cli-reference-how-to step 3 replaced with a link to the new supplemental-docs page
- New `cli-supplemental-docs.md` documents file naming, heading rules, and
`## Options` / `## Arguments` override syntax
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Enterprise Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughThis PR introduces a structured supplemental documentation system for CLI reference pages alongside a visual modifier badge component system. New CliSupplementalDoc parses markdown files into descriptions, parameter override dictionaries, and post-content sections. Command modifiers (destructive, confirmation, auth, idempotent, streaming, long-running, scope) are rendered as visual badges via a new directive block and Razor view. The CLI markdown generator refactored to use structured supplemental docs instead of raw strings, validates overrides against real parameters, and cleans reserved meta-commands from usage text. File classes and parser/renderer were updated to wire reserved meta-commands and supplemental documents through the generation pipeline. Comprehensive new documentation covers assembler workflows, changelog operations, and supplemental content authoring guidelines. 🚥 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 |
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
![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: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/Elastic.Markdown/Extensions/CliReference/CliMarkdownGenerator.cs (1)
129-134:⚠️ Potential issue | 🟠 Major | ⚡ Quick winNamespace
## Optionsoverrides are silently dropped.
AppendParametersis called withnulloverrides, so anyOptionOverridesparsed from a namespace supplemental doc never reach the rendered namespace flags. Combined withCliNamespaceFile.BuildMarkdownnot plumbing anemitError, writer typos in## Optionsfor a namespace produce neither an applied override nor a build error — they just vanish.CommandPageplumbs both, namespaces should match.🛠 Suggested fix (also thread an error callback like `CommandPage`)
- public static string NamespacePage(CliNamespaceSchema ns, CliSupplementalDoc? supplemental, string[]? fullPath = null, string? binaryName = null, string[]? reservedMetaCommands = null) + public static string NamespacePage( + CliNamespaceSchema ns, + CliSupplementalDoc? supplemental, + string[]? fullPath = null, + string? binaryName = null, + string[]? reservedMetaCommands = null, + Action<string>? emitError = null) { @@ - if (ns.Options.Count > 0) - { - _ = sb.AppendLine("## Namespace Flags"); - _ = sb.AppendLine(); - AppendParameters(sb, ns.Options, null); - } + if (ns.Options.Count > 0) + { + _ = sb.AppendLine("## Namespace Flags"); + _ = sb.AppendLine(); + AppendParameters(sb, ns.Options, supplemental?.OptionOverrides); + } + + if (supplemental is not null && emitError is not null) + { + var nsOptionNames = new HashSet<string>(ns.Options.Select(o => o.Name), StringComparer.OrdinalIgnoreCase); + foreach (var key in supplemental.OptionOverrides.Keys) + { + if (!nsOptionNames.Contains(key)) + emitError($"CLI supplemental: Option '--{key}' not found in namespace '{ns.Segment}'"); + } + }And in
CliNamespaceFile.BuildMarkdown:- return CliMarkdownGenerator.NamespacePage(_namespace, supplemental, _fullPath, _binaryName, _reservedMetaCommands); + return CliMarkdownGenerator.NamespacePage( + _namespace, supplemental, _fullPath, _binaryName, _reservedMetaCommands, + error => Collector.EmitError(_supplementalDoc ?? SourceFile, error));🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@src/Elastic.Markdown/Extensions/CliReference/CliMarkdownGenerator.cs` around lines 129 - 134, The namespace-level option overrides are being dropped because AppendParameters is called with null overrides and CliNamespaceFile.BuildMarkdown isn't passing an emitError callback; update the namespace rendering to call AppendParameters(sb, ns.Options, ns.OptionOverrides) (or the actual property that holds namespace OptionOverrides) so parsed overrides are applied, and modify CliNamespaceFile.BuildMarkdown to accept and thread an emitError callback through to the generator (matching CommandPage's plumbing) so writer typos produce build errors rather than silently disappearing.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/cli/changelog/cmd-render.md`:
- Line 8: The relative link target in the markdown text currently points to
"bundle-amend.md" which is incorrect; update the markdown link in the
docs/cli/changelog/cmd-render.md entry that references bundle-amend.md so it
instead points to the existing file "cmd-bundle-amend.md" (i.e., replace the
target "bundle-amend.md" with "cmd-bundle-amend.md" in the render command
description).
In `@docs/cli/cli-supplemental-docs.md`:
- Around line 19-27: The two fenced code blocks containing the directory
listings (the block starting with "cli/ assembler/ index.md ..." and the block
starting with "cli/ ns-assembler.md ...") must declare a fence language to
satisfy MD040; change their opening and closing fences from ``` to ```text so
both blocks are fenced as ```text ... ```text.
---
Outside diff comments:
In `@src/Elastic.Markdown/Extensions/CliReference/CliMarkdownGenerator.cs`:
- Around line 129-134: The namespace-level option overrides are being dropped
because AppendParameters is called with null overrides and
CliNamespaceFile.BuildMarkdown isn't passing an emitError callback; update the
namespace rendering to call AppendParameters(sb, ns.Options, ns.OptionOverrides)
(or the actual property that holds namespace OptionOverrides) so parsed
overrides are applied, and modify CliNamespaceFile.BuildMarkdown to accept and
thread an emitError callback through to the generator (matching CommandPage's
plumbing) so writer typos produce build errors rather than silently
disappearing.
🪄 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: 63ddb330-85e4-43a5-90fc-9f3644d4cdd6
📒 Files selected for processing (36)
docs/_docset.ymldocs/cli/assembler/bloom-filter/cmd-create.mddocs/cli/assembler/bloom-filter/cmd-lookup.mddocs/cli/assembler/cmd-build.mddocs/cli/assembler/cmd-clone.mddocs/cli/assembler/config/cmd-init.mddocs/cli/assembler/content-source/cmd-match.mddocs/cli/assembler/deploy/cmd-apply.mddocs/cli/assembler/deploy/cmd-plan.mddocs/cli/assembler/index.mddocs/cli/assembler/navigation/cmd-validate-link-reference.mddocs/cli/assembler/navigation/cmd-validate.mddocs/cli/changelog/cmd-add.mddocs/cli/changelog/cmd-bundle-amend.mddocs/cli/changelog/cmd-evaluate-pr.mddocs/cli/changelog/cmd-gh-release.mddocs/cli/changelog/cmd-init.mddocs/cli/changelog/cmd-remove.mddocs/cli/changelog/cmd-render.mddocs/cli/cli-reference-how-to.mddocs/cli/cli-supplemental-docs.mddocs/cli/cmd-assemble.mdsrc/Elastic.Documentation.Site/Assets/markdown/cli-modifiers.csssrc/Elastic.Documentation.Site/Assets/styles.csssrc/Elastic.Markdown/Extensions/CliReference/CliCommandFile.cssrc/Elastic.Markdown/Extensions/CliReference/CliMarkdownGenerator.cssrc/Elastic.Markdown/Extensions/CliReference/CliNamespaceFile.cssrc/Elastic.Markdown/Extensions/CliReference/CliReferenceDocsBuilderExtension.cssrc/Elastic.Markdown/Extensions/CliReference/CliRootFile.cssrc/Elastic.Markdown/Extensions/CliReference/CliSupplementalDoc.cssrc/Elastic.Markdown/IO/MarkdownFile.cssrc/Elastic.Markdown/Myst/Directives/CliModifiers/CliModifiersBlock.cssrc/Elastic.Markdown/Myst/Directives/CliModifiers/CliModifiersView.cshtmlsrc/Elastic.Markdown/Myst/Directives/CliModifiers/CliModifiersViewModel.cssrc/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cssrc/Elastic.Markdown/Myst/Directives/DirectiveHtmlRenderer.cs
- Thread OptionOverrides and emitError through NamespacePage so namespace supplemental ## Options are applied and typos are caught at build time - Add text language to directory tree fenced blocks in cli-supplemental-docs.md Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@src/Elastic.Markdown/Extensions/CliReference/CliMarkdownGenerator.cs`:
- Around line 283-308: The early return gated by hasModifiers in
CliMarkdownGenerator.cs prevents the cmd.Output?.Formats rendering block from
running when no modifiers are present; update the logic so output formats aren't
dropped — either include cmd.Output?.Formats (non-empty) in the hasModifiers
predicate or move the formats block (the block that checks cmd.Output?.Formats
and appends "**Output formats:**") above the hasModifiers early-return check;
locate the hasModifiers calculation and the cmd.Output?.Formats block in the
Generate/Write method and apply one of these fixes to ensure formats are always
emitted when present.
- Around line 218-232: The validation currently builds a single set allNames
from cmd.Parameters and checks both supplemental.OptionOverrides.Keys and
supplemental.ArgumentOverrides.Keys against it, allowing cross-matched keys
(option name matching a positional or vice-versa) to pass; change the validation
to build two separate name sets—one for flag/option parameter names and one for
positional/argument names—and validate OptionOverrides.Keys only against the
option-name set and ArgumentOverrides.Keys only against the positional-name set
(use existing symbols: supplemental, emitError, cmd, OptionOverrides,
ArgumentOverrides, and AppendParameters to locate where AppendParameters expects
options vs arguments).
🪄 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: 02d9b20c-b88b-4fae-9e95-b72259550257
📒 Files selected for processing (3)
docs/cli/cli-supplemental-docs.mdsrc/Elastic.Markdown/Extensions/CliReference/CliMarkdownGenerator.cssrc/Elastic.Markdown/Extensions/CliReference/CliNamespaceFile.cs
✅ Files skipped from review due to trivial changes (1)
- docs/cli/cli-supplemental-docs.md
🚧 Files skipped from review as they are similar to previous changes (1)
- src/Elastic.Markdown/Extensions/CliReference/CliNamespaceFile.cs
- Output formats block no longer skipped when command has no modifier pills - Option/argument override validation now checks against the correct parameter role subset so a flag name in ## Arguments (or vice-versa) is caught Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Member
Author
|
@coderabbitai review |
Contributor
✅ Actions performedReview triggered.
|
reakaleek
approved these changes
May 11, 2026
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.
Why
The auto-generated CLI reference pages from #3221 are accurate but bare — they only render what's in the schema JSON. Writers have no way to add prose context, usage walkthroughs, cross-references, or worked examples without editing the schema (which belongs to the CLI tool's codebase, not the docs repo).
What
Supplemental files for writers
Drop a markdown file into
docs/cli/matching the command or namespace name and it enriches the generated page automatically on the next build. No configuration required. If the filename doesn't match a real command, the build fails with an error — so renamed or removed commands can never leave orphaned docs silently.File naming mirrors the CLI structure:
What goes in a supplemental file is controlled by headings:
A file with no
##headings replaces the description entirely:Use
## Descriptionwhen you also want extra sections. Other##headings append after the generated parameter table — good for usage walkthroughs and worked examples:Full authoring guide at /cli/cli-supplemental-docs — a new page under Automated Reference.
:::{cli-modifiers}pill rowCommand metadata from the schema (destructive, requires-confirmation, auth required, idempotent, scope, streaming, long-running) now renders as a colour-coded pill row between the usage block and the description — same visual language as
applies-to. The generator emits it automatically; authors never write it by hand.Reinstated content for assembler and changelog namespaces
Before the schema-driven generator landed, the assembler and changelog command pages were hand-written static markdown files. Those pages were replaced by generated pages but the extra content — usage walkthroughs, platform-specific notes, cross-references, CI environment variable tables — was lost.
This PR reinstates all of it as supplemental files:
assemblelocal-workspace walkthrough.add(filenames table, product format and resolution, CI auto-detection env vars),bundle-amend(resolve behaviour, examples),evaluate-pr(GitHub Actions outputs table),gh-release,init,remove(directory resolution tables, profile-based vs option-based mode), andrender(output format reference).Other generator improvements
__argh_rootand otherReservedMetaCommandstokens are stripped from generated usage lines.notesfield is no longer rendered on pages — that content belongs in supplemental post-sections where writers control it.--dry-run,--force, output flags) get a compact quick-reference block above the full parameter table.Collectoris nowprotectedonMarkdownFileso CLI record subclasses don't need to storeBuildContextas a field, which was causing infiniteGetHashCoderecursion at startup.