Restore help content hidden by stale rpk description overrides - #1862
Merged
Conversation
A ground-truth review of every generated rpk page against the v26.2.1 binary's --help output found that description overrides had replaced the source help on dozens of commands, hiding operational content and in several cases contradicting the current binary. This change makes the overrides match reality: Wrong or outdated curated text replaced by the source help: - rpk cluster config lint said 'identify' where the command removes deprecated content - rpk cluster logdirs describe claimed record counts where the command reports data sizes, and dropped the du size caveat - rpk generate app listed five supported languages where only go exists - rpk cluster partitions balance claimed automatic balancing, which is Enterprise-only Continuous Data Balancing, and lost the CE/EE distinction - rpk cluster self-test start carried an outdated test catalog missing the dsync and 16 KB tests - rpk group seek described old --to flag semantics One-line summaries dropped so the full help renders (concepts, preconditions, file formats, field descriptions): rpk group, group delete, group describe, group offset-delete, rpk cluster maintenance (and enable/status), cluster health, cluster storage mount/unmount, cluster partitions list/move, cluster license set, generate license, generate grafana-dashboard, profile, profile set, profile prompt, shadow status, topic delete, topic list, topic trim-prefix, topic describe-storage, transform logs Curated summaries kept with the hidden help paragraphs appended: rpk security acl (five ACL components, multiplicative basis, safety guidance, per-client operation sets), ai auth login, ai oauth-client dcr (admission modes), ai oauth-client revoke-tokens, connect echo/install/lint/list/template/test (exit codes, examples, experimental warning), cluster quotas import (schema), shadow describe, topic create, transform init, debug remote-bundle download, cloud mcp install (redpandaCloud entry name) Also: - rpk topic produce now includes a produce-specific format partial (topic-format-produce.adoc): the shared consume partial documented consume semantics (raw sizes, print modifiers, consume-only escapes) that are wrong for produce (encoded sizes, parse modifiers, smaller escape set) - rpk topic consume: restored the unpack character legend and the connection-behavior guidance, and fixed the header example to match its own prose (spaces around key and value) - rpk security acl create: the schema-migration note said 'above' while rendering before the examples it references - curated details the help lacks are preserved as content items (topic delete irreversibility caution, maintenance enable upgrade guidance, cluster config propagation guidance) Verified by regenerating the full tree with doc-tools 5.3.0 and re-running the help-comparison sweep: every remaining description override is intentional curation, now also surfaced by the generator's new coverage report on every regen PR.
✅ Deploy Preview for redpanda-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
📝 WalkthroughWalkthroughUpdated Estimated code review effort: 4 (Complex) | ~45 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
JakeSCahill
added a commit
to redpanda-data/docs-extensions-and-macros
that referenced
this pull request
Jul 31, 2026
…laceholder braces in prose The Antora build of the restored-content corpus (redpanda-data/docs#1862) surfaced two rendering defects: - 4+ space indented literal chunks without a colon introducer (the 'kafka/{topic}/{partition}_{revision}/' path template in rpk cluster logdirs describe) rendered as prose, so Asciidoctor consumed the braces as attribute references and dropped them. Such chunks are now captured as code blocks when they start a blank-line-delimited chunk. Wrapped continuations of table rows and list items are excluded (a first attempt without the chunk-start guard broke the license-info field table and the txn state list, caught by corpus diffing). - Template placeholders like {name}_search in flag description prose (rpk ai mcp-server create/update) also rendered as attribute references. Prose segments now escape brace tokens, with {vbar} allowlisted because it is a real attribute used for pipe escaping. Backtick spans already had this protection. Also fixes rpk profile prompt config samples (backticks were injected into raw prompt strings) and the spurious trailing period on the rpk cluster partitions move-status column list, both via the literal capture.
JakeSCahill
added a commit
to redpanda-data/docs-extensions-and-macros
that referenced
this pull request
Jul 31, 2026
* feat(rpk-docs): refresh a single plugin's docs with --plugin
rpk plugins (connect, ai, k8s, check) release on their own cadence,
independent of rpk itself, so their docs go stale between Redpanda
releases. Add a --plugin mode that installs one plugin against an rpk
binary matching the committed snapshot's version, splices the fresh
subtree into the snapshot, records the plugin version, and re-renders
the full tree. Re-rendering everything keeps stale-file cleanup, nav
rebuilds, and override validation correct: only the plugin's pages
change in git.
The rpk binary comes from the official release download when the
snapshot points at a published release, with a build-from-source
fallback for RC snapshots (RC releases are drafts, so their assets
are not publicly downloadable). --rpk-bin skips both for local runs.
Also populate plugin_versions, which the page templates already
support but nothing ever fed: --plugin records the refreshed version,
the from-source path records manifest versions for plugins that
installed, and --from-json now passes recorded versions through
instead of hardcoding {}.
* fix(rpk-docs): preserve platform markers and survive rejected version pins
The fresh plugin subtree from --print-tree carries no platforms fields,
so splicing it dropped :page-platforms: from every plugin page. Reapply
markers using the snapshot's recorded linux_only_commands.
rpk's install version validation caps each version segment at two
digits, so pins like connect 4.102.0 are rejected. Fall back to
installing latest (at dispatch time latest is the release that
triggered the run) and record the manifest-resolved version instead of
the failed pin.
* docs: Auto-update CLI reference documentation (PR #225)
* feat(rpk-docs): stamp new plugin commands with the plugin's own version
New commands found during a --plugin refresh now get
introducedInVersion set to the plugin version that shipped them, so
pages render "This command was introduced in <plugin> version X". The
full-regen path gets the same treatment: plugin-subtree commands are
stamped with the plugin's version instead of the rpk version, which
would have rendered a Redpanda version masquerading as a plugin
version. Stamping happens before the overrides load, so notes appear in
the same run's output. Existing introducedInVersion values are never
overwritten.
Verified against main's snapshot: an ai refresh stamped 30 new commands
with 0.2.31 and the rendered partials carry the note.
* feat(rpk-docs): support per-plugin version pins during full generation
Full regenerations install the latest published version of every
plugin, so beta-only plugins (no version promoted to latest in the
manifest) install nothing and their commands are absent from the tree —
how the k8s pages went missing during the 26.2 beta window. A
repeatable --plugin-pin name=version option now pins individual plugin
installs, with the same retry-without-pin fallback as --plugin-version,
and pinned versions are recorded in plugin_versions.
* docs: Auto-update CLI reference documentation (PR #225)
* fix(rpk-docs): report every detected change category in diffs and PR summaries
The diff engine computed flag type, required, and description changes
and then discarded them. The PR summary read a summary field that never
existed (changedDescriptions vs descriptionChanges), never rendered
changed defaults at all, and claimed 'no changes' for releases whose
only changes were defaults or descriptions. The console report labeled
removals as deprecations.
Collect all computed flag changes into the diff, render every category
in the PR summary with itemized collapsible lists, extend the What's
new section with removed commands/flags and flag type changes, label
removals as removals, and JSON-encode structured default values so
arrays never render as [object Object].
Verified against the real v26.1.12 -> v26.2.1 diff: surfaces a
previously invisible default change (rpk container start
--console-image v3.7.1 -> v3.8.0), 1 flag description change, and 35
command description changes alongside the 53/33/23 command and flag
counts.
* feat(rpk-docs): detect and report command deprecations
The source scanner's deprecated_commands output was stored in every
snapshot and never read again: deprecations were invisible to the diff,
What's new, and PR summaries, while hidden-deprecated commands were
misreported as removals (a command family that still works as aliases
looked deleted).
Diff the deprecation maps between snapshots to produce a real
newly-deprecated category carrying the deprecation message and
replacement, reclassify removals under a newly deprecated path as part
of that deprecation (with the affected subcommands listed), and render
deprecations in the console report, the What's new section, and the PR
summary. Visible deprecated commands are also annotated in the
overrides file automatically so their pages carry deprecation banners;
hidden ones are excluded because they have no pages to annotate.
Verified against the real v26.1.12 -> v26.2.1 diff: the rpk redpanda
admin family reports as 4 deprecations with the rpk cluster migration
message, and removals drop from 33 to 21.
* feat(rpk-docs): merge What's-new updates instead of one-shot writes
The What's-new updater refused to write when the page already had any
Redpanda CLI section, so only the first run per release-notes page ever
landed: later RCs in a beta cycle were silently dropped, re-runs could
never refresh, and the hand-written section from the 26.2 cycle blocked
the v26.2.1 GA entry entirely.
Wrap generated content in version-scoped AUTOGEN-RPK-CHANGES marker
blocks. Re-runs for the same version replace their own block, later
versions append inside the existing section, hand-written prose is
never touched, and a missing section is created at the standard
insertion points.
Plugin refreshes now write What's-new blocks too (labeled with the
plugin and its version) when --update-whats-new is passed — plugin
changes never arrive through a Redpanda release diff, so this was their
only path onto the page. Plugin entries render without xrefs because
plugin subtrees may render as partials, and Redpanda-release entries
now skip xrefs for excluded and partial-routed commands (rpk ai links
pointed at pages that do not exist). New-command bullets use only the
first line of help text so multi-line descriptions stop breaking the
list.
Verified on the real release-notes page: the hand-written 26.2 section
survives, a v26.2.1 block and an ai plugin 0.2.31 block accumulate
inside it, and the deprecation entry renders as one rolled-up
rpk redpanda admin item with all 11 subcommands listed.
* feat(rpk-docs): separate plugin changes into their own What's-new section
Plugin releases are not tied to the Redpanda version the What's new
page is about, so mixing their blocks into the Redpanda CLI section
implied the changes shipped with that release. Plugin blocks now land
in their own '== rpk plugins' section, and every autogen block opens
with a '=== <version>' heading (categories nest at ====), so
accumulated blocks from successive RCs or plugin releases never
produce colliding section ids.
* fix(rpk-docs): extract plugin command flags and fix generator output defects
Plugin subtrees come from --help-autocomplete, which carries no flag
data, so every plugin command page rendered an empty flags section —
rpk ai llm-provider create documented none of its two dozen flags
(reported in adp-docs#161 review). The plugin binary is installed
during generation, so harvest each command's --help output: parse the
local Flags section (shorthand, value type, default, wrapped
descriptions), skip rpk-core global flags, and leave the compiled-in
shim commands alone. Wired into both the single-plugin refresh and the
Docker full-generation path; help failures are non-fatal.
Also from the same review:
- Sentence extraction ate leading text around decimal versions:
'Run the OAuth 2.0 device...' became '0 device...' because the
sentence regex requires whitespace after punctuation and silently
drops unterminated prefixes. Protect decimals and glue back any
skipped prefix, in both capToTwoSentences and shortDescription.
- Repeat :description: inside the single-source tag region so stub
consumers inherit meta descriptions; page-aliases stays outside the
tag so consumers cannot inherit alias registrations.
- Collapse blank-line runs left by absent optional sections (plugin
pages had 3-5 empty lines between Usage and Examples), preserving
blank lines inside delimited blocks.
Verified with a real ai plugin refresh: 52 commands enriched, 54 pages
now carry a local Flags section (was 2), rpk ai llm-provider create
renders 23 flags, rpk ai auth login documents --no-browser, and its
description reads 'Run the OAuth 2.0 device authorization grant...'
in full.
* ci: retrigger Netlify preview with raised Node heap
* fix: persist linux_only_commands through plugin snapshot refreshes (CodeRabbit)
The Linux-only command list comes from Go build-tag scanning of the rpk
source, which from-json runs (including --plugin refreshes) never see.
A new preserveLinuxOnlyCommands helper inherits the list from whichever
stored tree carries it, both when deriving the working tree and right
before the refreshed snapshot is saved, so platform markers survive
every from-json round trip. Covered by new unit tests.
* fix(rpk-docs): correct What's-new xrefs and cap bullets at sentence boundaries
From review on #225:
- Command-group roots (rpk check, rpk k8s) render into their own
directory, but commandPathToXref linked them at the top level, so the
What's-new published broken xrefs for every new command group. Route
two-part commands with subcommands to <group>/<group>.adoc using the
tree in hand at render time.
- makeLinkablePredicate only consulted overrides routing, missing the
hardcoded rpk cloud / rpk security secret partials routing, so the
What's-new linked pages that exist only as cloud-docs partials. Those
commands now render as plain names.
- New-command bullets took the first line of help text, which cuts
wrapped cobra output mid-sentence. Cap at the first sentence boundary
instead, with decimal-version protection.
* fix(rpk-docs): retry container builds and verify the binary exists
Module downloads from proxy.golang.org fail transiently, and a
post-crash Docker daemon has been observed returning success for a
build that produced no binary, which sent every subsequent exec against
a missing /tmp/rpk. Retry the in-container build up to three times
(later attempts reuse the partially filled module cache) and verify
/tmp/rpk exists before proceeding.
* fix(rpk-docs): keep the Linux tree when the Darwin comparison build fails
The dual-build platform detection wrapped both builds in one try:
a native comparison-build failure (local Go older than go.mod requires)
was reported as a Docker failure, discarded the successful Linux tree,
and died in the native fallback for the same reason. The Linux tree is
authoritative; a comparison failure now only skips dynamic platform
detection.
* fix(rpk-docs): retry phantom-success container builds
docker exec intermittently returns zero for a build that produced no
binary (reproduced twice on Docker Desktop 29.6.1). The existence check
ran after the retry loop, so a phantom success failed the run instead
of retrying. Verify the binary inside the loop and treat a zero exit
with no binary as a failed attempt.
* feat(rpk-docs): stub reconciler for single-source consumer repos
adp-docs publishes rpk ai through one static stub page per command plus
a nav entry. A plugin release that adds a command leaves it invisible on
the ADP site (no stub), and one that removes a command leaves a stub
with an unresolved include (broken page) — the manual follow-up flagged
in review.
Add doc-tools generate rpk-plugin-stubs: reconciles a consumer repo's
stubs and nav against the docs repo's generated partials. Creates stubs
for new partials (title read from the partial — dashified filenames
cannot be reversed unambiguously), deletes managed stubs whose partial
is gone, never touches pages that do not match the managed-stub shape,
rebuilds the plugin's nav block hierarchically, and proposes page
aliases for likely renames (same parent, same depth, related last
words) for the reviewer to confirm. Full reconcile rather than a diff,
so it is idempotent and heals pre-existing drift.
Verified dry-run against real adp-docs + docs main: detects exactly the
two stubs that would resurrect from the stale partials docs#1849
removes, and nothing else.
* docs: Auto-update CLI reference documentation (PR #225)
* fix(rpk-docs): stop linking partial-routed subcommands from parent pages
The subcommand list on parent pages filtered overrides-based routing
but not the hardcoded rpk cloud / rpk security secret partials routing,
so rpk-security.adoc linked rpk-security-secret.adoc — a page that does
not exist. Found by building the full site from generated output; the
broken xref was pre-existing on the published site.
* feat(rpk-docs): parse urfave/cli help so Redpanda Connect flags extract
Flag extraction parsed only cobra's Flags: section, so connect (built
on urfave/cli, which prints OPTIONS:) extracted zero flags while ai and
k8s worked. Add a urfave parser (comma shorthands, value placeholders,
repeatable [ --x value ] notation, (default: ...) suffixes, GLOBAL
OPTIONS skipped) and dispatch on the section header. Verified: rpk
connect run renders 15 flags from real plugin help.
* feat(rpk-docs): support page-family sources in the stub reconciler
rpk connect renders as pages in the docs repo (not partials like ai and
cloud), and every generated page carries the single-source tag, so
consumer repos can stub page-family resources the same way. Parameterize
the source path and recognize page$ includes as managed stubs.
Enables the requested rpk connect CLI reference on the RPCN site
(DOC-2355 / rp-connect-docs#132): a dry run against real rp-connect-docs
generates the full connect stub set from docs main.
* fix(rpk-docs): never delete pages for plugins absent from the tree
rpk core ships only an install/uninstall/upgrade shim for managed
plugins. When the generation environment lacks a plugin binary, the
plugin's real commands are missing from --print-tree, and the
generator treated its pages and nav entries as stale and deleted
them. This happens every pre-GA window: the plugin publisher only
promotes stable X.Y.Z releases, so 'rpk <plugin> install' resolves
nothing until GA. The v26.2.1-rc2 regen deleted the five rpk k8s
multicluster pages this way (redpanda-data/docs#1831).
Auto-detect known plugins whose subtree is absent or shim-only and
preserve their existing pages and nav entries, deduplicating against
entries regenerated in the same run. Also track failed plugin
installs in the source-build path for the generation log.
Verified against a copy of the docs beta rpk reference with a
plugin-less v26.2.1-rc2 tree: all four shim-only plugin directories
preserved, 26 plugin nav entries kept, zero plugin pages deleted,
while non-plugin regeneration proceeds normally.
* fix(rpk-docs): stop help-text underlines from breaking generated pages
Command help text often underlines section titles with a run of = or -
characters and uses ALL-CAPS column-header rows in aligned sample
output. The section parser promoted the titles to headings but left
the underline in the content, where a line of 4+ = characters is an
AsciiDoc example-block delimiter, producing an unterminated block
(seen on rpk cluster brokers decommission-status, and previously on
its rpk redpanda admin predecessor). It also promoted multi-space
column-header rows such as 'PARTITION REASON' to section
headings, splitting sample tables.
Consume the underline when it directly follows a section header, treat
lines containing multi-space runs as content rather than headers, and
warn if any bare delimiter run still reaches section content.
Verified by regenerating all 355 pages from the v26.2.1-rc2 tree: the
decommission-status sections now render with their tables intact, and
no bare delimiter runs remain outside code fences.
* fix: add regression tests for protected-plugin cleanup and nav dedup (CodeRabbit)
Covers auto-protection when a known plugin is absent or shim-only,
explicit protectedPlugins, protected plugin directories surviving the
stale-file sweep while genuinely stale pages are still deleted, and
preserved nav entries not duplicating entries that are also present in
the regenerated output.
* fix(rpk-docs): stop shim-only runs from rewriting plugin pages and misplacing nav entries
Protection for managed plugins previously only exempted their pages from
the stale-file sweep. Two gaps remained when the tree had a plugin's shim
(install/uninstall/upgrade) but not its real commands:
- Pages under the plugin subtree were still written, so the parent page
(e.g. rpk-k8s.adoc) was regenerated with a shim-only Subcommands table,
orphaning the preserved child pages.
- Preserved nav entries were appended after all generated entries, so
they rendered nested under the wrong parent at the end of the section.
Protection now covers the whole pipeline. Protected plugins are detected
before the write loop (explicit callers merged with shim-only/absent
auto-detection) and generation skips their entire subtree, parent page
included, exactly like the fully-absent case. updateNavFile no longer
generates entries for protected plugins. It preserves each plugin's
previous nav block (parent plus nested children) and splices it back in
at its original position, anchored to the nearest preceding surviving
entry. In the common shim scenario the nav and every plugin page come
out byte-identical to the previous run.
The preservation log line now lists only plugins that actually had nav
entries preserved instead of every protected plugin.
* fix(rpk-docs): pass failed plugin installs to generation as protected plugins
fetchRpkTreeFromLinuxSource collected failedPlugins but never used it.
It now returns { tree, failedPlugins } and the handler threads the list
into both generateRpkDocs calls as explicit protectedPlugins, merged
there with auto-detection, so a failed install can never delete or
rewrite that plugin's existing docs even if the shim heuristic changes.
Also drop the handler's duplicate KNOWN_PLUGINS definition and share the
single constant exported by generate-rpk-docs.js (the handler still
re-exports it for existing consumers).
* fix(rpk-docs): treat open-block delimiters as content boundaries in blank-line collapse
Two published pages carry -- open blocks from override content; blank
lines inside them are content and must survive the collapse pass.
* fix(rpk-docs): address second-round review on flag parsing, page conflicts, and stub safety
Blocking findings:
- Wrapped help continuation lines beginning with a flag-like token
('(alias: --x-ref)' wraps to '--x-ref)') were silently dropped by the
dash guard, truncating 20 published flag descriptions. Continuations
are now any line indented deeper than the flag column that did not
parse as a flag, in both the cobra and urfave parsers.
- Pages with a curated 'Flags' override section rendered a second,
conflicting extracted table (rpk connect run). Curation wins: the
extracted table is skipped with a warning telling maintainers the
override can be dropped to adopt it.
- The stub reconciler could create a page whose name another page
claims via :page-aliases:, making the consumer's Antora build fatal.
It now skips such names, excludes them from nav, and reports them.
Verified on real adp-docs: the dry run is a clean no-op with both
collisions surfaced, independent of upstream cleanup order.
Non-blocking findings:
- --plugin now falls back to a container build when local Go is older
than go.mod requires and Docker is available, matching the --ref
path's tolerance.
- Override validation errors reach the PR summary (stale entries were
invisible in automated PRs while the summary claimed all-clear).
- The plugin PR summary describes the real blast radius (full-tree
converge), and stub deletions with no rename partner are flagged for
redirect decisions.
* fix: clean dangling example fragments and warn on duplicate rendered headings
Ground-truth review of a full v26.2.1 generation against 348 --help dumps
found two rendering defects:
- Upstream help strings that end mid-example (rpai --order-by, --clear)
rendered as 'for example,.'. Strip a dangling 'e.g.' that has nothing
after it, and remove stray spaces before closing parentheses
(rpk group offset-delete -t).
- Pages can render the same level-2 heading twice when override content
collides with generated sections (rpk container status Example, fixed
in the docs overrides). The generator now warns per page so this class
is caught at generation time.
* fix: keep rpk root page in nav and cut What's-new summaries at paragraph breaks
Antora build of a full v26.2.1 generation surfaced both:
- The nav rebuild dropped the 'xref:reference:rpk/rpk.adoc[]' entry
(the root command page is skipped by the per-command entry loop), so
Antora reported the page as unlisted. The root page is now the first
static nav entry, matching the hand-maintained nav on main.
- What's-new command summaries glued a periodless cobra summary line to
the paragraph after it ('Install Redpanda Check This command
installs...'). firstSentence now cuts at the first blank line before
joining hard-wrapped lines, which preserves wrapped single-paragraph
descriptions.
* fix: do not label backfilled plugin flags as newly introduced
The v26.1.12 baseline snapshot predates plugin flag extraction, so every
plugin subcommand recorded zero flags. Diffing against it marked all 208
extracted ai/connect flags as new and stamped them 'New in 0.2.32' /
'New in 4.102.0', even for long-standing flags like rpk connect blobl
--pretty.
generateRpkDiff now treats a pre-existing command whose baseline recorded
no flags as documentation backfill: its flags are excluded from newFlags
(so no New-in labels and no What's-new entries) and reported in a
separate flagDataBackfilled category that surfaces in the diff report and
PR summary. Genuinely new commands and commands with baseline flag data
are unaffected, as are description-change checks on backfilled commands.
* fix: scope the backfill guard to plugin groups and stamp before rendering in from-json runs
Two refinements from verifying the backfill guard against the real
v26.1.12 to v26.2.1 snapshots:
- The guard now only treats a zero-flag baseline as backfill when the
command's whole top-level group recorded no flag data outside the
rpk-native install/uninstall/upgrade shims. Six core commands (for
example rpk cluster config status) legitimately gained their first
flag in v26.2.1 and were being swallowed. Result on real data: 23
genuine core flag additions reported, 50 plugin commands classified
as backfill, zero misfires either way.
- --from-json --diff runs now stamp introducedInVersion into the
overrides before the overrides load, so the same run renders the
labels instead of deferring them to the next regeneration. The
from-source stamping gate also fires on flag-only releases now, not
just when new commands exist.
* fix: capture unindented shell examples and colon-introduced code samples verbatim
Ground-truth review against rpk v26.2.1 --help output found the generator
mangling help text it had no rule for:
- Column-0 '$ command' examples with sample output (rpk cluster brokers
decommission-status) rendered as prose: the invocation got backticks
and a period, the output's =-underlined title became a spurious
section heading, and the ASCII table leaked into the Usage section.
These now render as a [,bash] command block plus a [.no-copy] output
block, and parseDescriptionSections no longer treats an all-caps line
directly after a $ invocation as a section header.
- Indented code introduced by a colon (Cedar policies on rpk ai policy
create, rpai command examples) rendered as prose with backticks
injected into the code. These are captured verbatim into [,text]
blocks. Column-aligned definition layouts are left to the existing
indented-table converter, which renders them as tables.
- 'e.g.:' rendered as 'for example, :'.
- Summaries (:description:, subcommand tables) now strip captured code
blocks, and a block introduced by a colon ends the summary at that
sentence.
- textTransformations rules gain an opt-in applyToCode flag so the
rpai -> rpk ai binary-name rewrite reaches code blocks while
admonition and backtick rules never touch verbatim content.
* chore: allow applyToCode in the overrides schema
* fix: protect example command lines from caption transforms and add description-coverage reporting
Two more findings from the ground-truth content review:
- The examples pipeline applied every textTransformations rule to raw
examples content before code-block wrapping, so a caption rule
rewrote '{"quotas":...}' inside an example invocation to
'{`quotas`:...}'. Examples content is now transformed line by line:
indented command lines only receive rules flagged applyToCode.
- Structured example captions ending in a period rendered with two
('brokers 1 and 2..'): the template appended an unconditional period.
Both example templates now use the ensurePeriod helper.
- New PR-summary section lists description overrides that replace
substantially longer source help (counting appendToDescription), so
curated-content drift stays visible for review on every regen PR
instead of hiding until the next audit.
* fix: render deeply indented help literals as code blocks and escape placeholder braces in prose
The Antora build of the restored-content corpus (redpanda-data/docs#1862)
surfaced two rendering defects:
- 4+ space indented literal chunks without a colon introducer (the
'kafka/{topic}/{partition}_{revision}/' path template in rpk cluster
logdirs describe) rendered as prose, so Asciidoctor consumed the braces
as attribute references and dropped them. Such chunks are now captured
as code blocks when they start a blank-line-delimited chunk. Wrapped
continuations of table rows and list items are excluded (a first
attempt without the chunk-start guard broke the license-info field
table and the txn state list, caught by corpus diffing).
- Template placeholders like {name}_search in flag description prose
(rpk ai mcp-server create/update) also rendered as attribute
references. Prose segments now escape brace tokens, with {vbar}
allowlisted because it is a real attribute used for pipe escaping.
Backtick spans already had this protection.
Also fixes rpk profile prompt config samples (backticks were injected
into raw prompt strings) and the spurious trailing period on the
rpk cluster partitions move-status column list, both via the literal
capture.
---------
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
This was referenced Aug 2, 2026
micheleRP
approved these changes
Aug 2, 2026
micheleRP
left a comment
micheleRP
left a comment
Contributor
There was a problem hiding this comment.
Approving, with one rebase note. This got a full verification pass rather than a read: I diffed the overrides semantically against the merge base, spot-checked the factual claims against the extracted help in the committed snapshot, and regenerated with the branch's overrides on top of current main.
Verified
- True change set vs merge base: 6 entries removed, 44 edited, 0 added. Worth stating explicitly because a naive comparison of this branch's file against today's
mainshows three phantomexclude: trueadditions for therpk ai connectionfamily — that is base drift (#1869 removed those excludes on main after this branch was cut), and this PR's diff never touches them. Merging keeps main's removal, so the connection pages are unaffected. - All five factual claims I spot-checked hold against the source help in the snapshot:
rpk cluster config lintremoves deprecated content where the curated text said "identify";rpk cluster logdirs describereports data sizes where the curated text claimed record counts;rpk cluster partitions balancehas the CE/EE distinction the curated text erased;rpk generate appandrpk group seekas described. - Regenerated with these overrides on current main: no new validation errors from any of the ~50 touched entries. (The 4 stale-path errors and the duplicate
== Examplewarning in the log are main's pre-existing issues, owned by #1865 and #1860.) - The two committed pages are byte-stable under regeneration — they are exactly what the generator produces from the new overrides, so nothing here drifts at the next regen.
- 62 pages change when the tree regenerates — committing only the 2 and letting the rest propagate through the re-render pipeline is consistent with #1863's design, and worth knowing when that PR lands so the 60-page auto-PR is not a surprise.
Rebase note
This is the one PR in the overrides queue that conflicts: with #1838 and #1865, in either direction. I merged the other three first and attempted this one — three conflict regions, all mechanical:
- A same-entry field union where #1838 adds
selfHostedOnly: trueand this PR edits the same object'sdescription. Keep both. rpk cluster config lint(deleted here) adjacent torpk cluster storage restore-start(deleted in #1865). Both deletions stand.rpk connect studio sync-schema(deleted in #1865) adjacent torpk transform logsandrpk generate license(deleted here). All three deletions stand.
So: rebase after #1838/#1860/#1865 merge, resolve by union, nothing judgmental.
One caveat for the record: the extended rpk ai auth login and rpk ai oauth-client dcr descriptions add operational claims (credentials-file permissions, the public registration endpoint path) that I could not verify against the gateway source from here. They read consistent with the documented behavior; flagging only so the unverified bits are known. Those descriptions flow into adp-docs through the single-source stubs.
This was referenced Aug 3, 2026
…aves Resolves the rpk-overrides.json conflict by semantic reconstruction: main's last valid state plus the #1838 selfHostedOnly gating (22 commands, re-asserted for the two whose entries this PR empties) plus this PR's 55 content deltas, each set verified programmatically. This also repairs the invalid JSON that the #1838 squash-merge left on main (three unresolved conflict hunks), superseding the standalone hotfix in #1874.
![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
🤖 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-data/rpk-overrides.json`:
- Line 1328: Update the format documentation associated with the
component-listing command so its supported values are consistent: include
jsonschema alongside text, json, and cue in the format flag description, or
remove the jsonschema usage from the description. Preserve the documented
bloblang-functions and bloblang-methods behavior.
In `@modules/reference/partials/topic-format-produce.adoc`:
- Around line 14-18: Update the escape-description table in topic-format-produce
so the `\\` entry is labeled “Backslash” instead of “Slashes,” while leaving the
other escape descriptions unchanged.
🪄 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: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: b7f8d504-fd2d-4d22-ac65-2667d43a8d15
📒 Files selected for processing (3)
docs-data/rpk-overrides.jsonmodules/reference/pages/rpk/rpk-topic/rpk-topic-produce.adocmodules/reference/partials/topic-format-produce.adoc
| }, | ||
| "rpk connect list": { | ||
| "description": "List available Redpanda Connect components. Shows inputs, outputs, processors, caches, rate limits, buffers, metrics, and tracers that can be used in pipelines.", | ||
| "description": "List available Redpanda Connect components. Shows inputs, outputs, processors, caches, rate limits, buffers, metrics, and tracers that can be used in pipelines.\n\nIf any component types are explicitly listed, only types of those components are shown.\n\nWhen using `--format jsonschema` with `bloblang-functions` or `bloblang-methods`, you can optionally specify function or method names to retrieve metadata for only those items, for example `rpk connect list --format jsonschema bloblang-functions uuid_v4`.", |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Document jsonschema consistently.
Line 1328 documents --format jsonschema, but the format flag description lists only text, json, and cue. Add jsonschema to the flag description, or remove the unsupported format from this command description.
🤖 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 `@docs-data/rpk-overrides.json` at line 1328, Update the format documentation
associated with the component-listing command so its supported values are
consistent: include jsonschema alongside text, json, and cue in the format flag
description, or remove the jsonschema usage from the description. Preserve the
documented bloblang-functions and bloblang-methods behavior.
Comment on lines
+14
to
+18
| |`\t` |Tabs | ||
| |`\n` |Newlines | ||
| |`\r` |Carriage returns | ||
| |`\\` |Slashes | ||
| |`\xNN` |Hex encoded characters |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Correct the \\ escape description.
Line 17 labels \\ as “Slashes”. This escape represents a literal backslash. Use “Backslash” to prevent users from interpreting it as /.
🤖 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 `@modules/reference/partials/topic-format-produce.adoc` around lines 14 - 18,
Update the escape-description table in topic-format-produce so the `\\` entry is
labeled “Backslash” instead of “Slashes,” while leaving the other escape
descriptions unchanged.
…ption micheleRP's #1860 review: json round-trips flattened the escape to a literal invisible character, making previously self-documenting source unreadable. Restored the escape (byte-identical semantics).
This was referenced Aug 3, 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.
What
A ground-truth review of every generated rpk reference page against the v26.2.1 binary's
--helpoutput (part of the automation work in redpanda-data/docs-extensions-and-macros#225) found thatdescriptionoverrides indocs-data/rpk-overrides.jsonhad replaced the source help on dozens of commands. Because overrides win on every regeneration, the automation would faithfully reintroduce the stale content forever. This PR fixes the overrides so regeneration produces accurate pages, and pairs with a new generator report that keeps future drift visible.Changes by class
Curated text that contradicts the current binary, replaced by the help:
rpk cluster config lintsaid "identify" where the command removes deprecated contentrpk cluster logdirs describeclaimed record counts where the command reports data sizesrpk generate applisted five supported languages where onlygoexistsrpk cluster partitions balanceclaimed automatic balancing (Enterprise-only) and lost the CE/EE distinctionrpk cluster self-test startcarried an outdated test catalog (missing the dsync and 16 KB tests)rpk group seekdescribed old--tosemanticsOne-line summaries dropped so the full help renders (concepts, preconditions, file formats, per-field descriptions): rpk group family, cluster maintenance family, cluster health, cluster storage mount/unmount, cluster partitions list/move, cluster license set, generate license, generate grafana-dashboard, profile/profile set/profile prompt, shadow status, topic delete/list/trim-prefix/describe-storage, transform logs.
Curated summaries kept, hidden help paragraphs appended: rpk security acl (ACL components, multiplicative basis, safety guidance), ai auth login, ai oauth-client dcr (admission modes), ai oauth-client revoke-tokens, connect echo/install/lint/list/template/test (exit codes, examples, experimental warning), cluster quotas import (import schema), shadow describe, topic create, transform init, debug remote-bundle download, cloud mcp install.
Produce/consume format split:
rpk topic produceincluded the shared consume-orientedtopic-format.adocpartial, which documents consume semantics that are wrong for produce (raw vs encoded sizes, print vs parse modifiers, a different escape set). Addedtopic-format-produce.adocwritten from the produce help and switched the produce page and override to it. Also restored the consume unpack legend and connection-behavior section, and fixed the consume header example to match its own prose.Curated details the help lacks are preserved, not deleted: topic delete irreversibility caution, maintenance enable upgrade guidance, cluster config propagation guidance, Serverless and BYOC notes, all xref-enriched items.
Why the automation won't reintroduce this
Validation
Regenerated the full rpk tree with the updated overrides and doc-tools 5.3.0, then re-ran the help-comparison sweep across all 344 command pages: zero critical findings, all 364 files parse clean under Asciidoctor, and every remaining description override is intentional curation. Rendered pages ship in the next regeneration (the planned v26.2.1 re-dispatch), except the produce include swap, which is applied directly so the wrong format docs stop rendering now.
Related PRs (rpk docs automation train)
See redpanda-data/docs-extensions-and-macros#225 for the train overview. Merge alongside #1860 and #1861 (non-overlapping edits to the same files).
Jira
Part of DOC-2408 (stale rpk overrides hide or contradict source help).