Remove duplicate Example heading on rpk container status

[JakeSCahill]

What

Three related changes (the review rightly flagged that the original body described only the first):

1. rpk container status renders two == Example headings — live on the published page. The override carried two content items that each emit the heading: a self-hosted item with == Example hard-coded in its content, and a section item titled Example. Merged the Quick Start lead-in (still wrapped in ifndef::env-cloud) into the single Example section, and applied the same fix to the rendered page so it takes effect before the next regeneration.

2. applyToCode: true on the rpai text transformation. doc-tools 5.3.1 captures help command examples into verbatim code blocks, where only rules flagged applyToCode run. Without this flag the published examples tell readers to run the internal plugin binary name — five occurrences in rpk-ai-agent-a2a-send.adoc alone render rpai agent a2a send ... instead of rpk ai agent a2a send .... This changes published command examples at the next regeneration.

3. The matching applyToCode property declared in rpk-overrides.schema.json, which is what lets the Validate rpk-overrides.json check accept the new key.

Also restores the ‌ escape that a json round-trip had flattened to a literal invisible character (review finding — byte-identical semantics, readable source).

Validation

Found by the ground-truth review (every generated page checked against rpk --help output). Regenerated the full tree with the updated override and confirmed one Example heading, the sample output in both builds, and the Quick Start pointer only when env-cloud is unset. The duplicate-heading warning added in doc-tools 5.3.0 makes this class self-reporting at generation time.

Jira

Part of DOC-2408.

Related PRs (rpk docs automation train)

See redpanda-data/docs-extensions-and-macros#225 for the train overview. The rpai-in-inline-spans and backtick-splitting follow-ups from the review are being fixed in doc-tools (they live in the transformation chain, not this data).

[netlify]

✅ Deploy Preview for redpanda-docs-preview ready!

Name	Link
🔨 Latest commit	4ac8d64
🔍 Latest deploy log	https://app.netlify.com/projects/redpanda-docs-preview/deploys/6a706d5680ab980008f4180a
😎 Deploy Preview	https://deploy-preview-1860--redpanda-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 8f728c50-4ad7-40ea-8e92-f23c3f61e3d7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The documentation transformations now apply the rpai replacement inside code blocks and remove an invisible character from the bare-flag description. The container-status example now combines the self-hosted quick-start note with the example content for non-cloud environments. The example heading appears for all environments, while the quick-start guidance remains excluded from cloud builds.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: feediver1, paulohtb6

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the primary change: removing the duplicate Example heading from the rpk container status page.
Description check	✅ Passed	The description explains the changes, validation, Jira reference, and related work, but omits the template's page preview and review deadline.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Fix failing CI checks

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cleanup/container-status-duplicate-example

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 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`:
- Around line 326-327: Update the replacement-item definition in
rpk-overrides.schema.json to declare applyToCode as a boolean property, allowing
the existing field in rpk-overrides.json under additionalProperties: false.
Ensure the schema validation for this override runs in CI.

🪄 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: 1599bb0d-ebf4-4ba4-9acc-32d32d7cf9b5

📥 Commits

Reviewing files that changed from the base of the PR and between 32c36c6 and c89bc52.

📒 Files selected for processing (2)

• docs-data/rpk-overrides.json
• modules/reference/pages/rpk/rpk-container/rpk-container-status.adoc

[micheleRP]

Reviewed and verified by regenerating both ways. The container-status fix is correct and yours is the better of the two versions, so I have made room for it. Not approving yet only because of the undescribed scope, which is worth putting on the record before this lands.

Overlap with #1865, already resolved on my side

The rpk container status override hunk here is byte-for-byte identical to a commit that was on michele/rpk-overrides-cleanup in #1865, and both branches started from the same blob, so whichever merged second would have conflicted on that entry.

Yours also fixes the rendered page, so the duplicate heading disappears now instead of at the next regeneration, which mine did not do. I have dropped that commit from #1865 and rebased, so this PR owns the fix and there is no longer a conflict. #1865 keeps only the stale-command-path cleanup and the rpk connect run Flags table, neither of which this PR touches.

Undescribed changes

The body describes the Example heading fix, but this PR also makes three other changes:

1. applyToCode: true on the rpai text transformation. This is a real improvement and I would call it out in the body, because it changes published command examples. Regenerating with and without it:

   - rpai agent a2a send financial-advisor "What moved the S&P 500 today?"
   + rpk ai agent a2a send financial-advisor "What moved the S&P 500 today?"

   Five such examples in rpk-ai-agent-a2a-send.adoc alone were telling readers to run the internal plugin binary name.

2. The matching applyToCode property in rpk-overrides.schema.json, which is what lets the repo's Validate rpk-overrides.json check accept the new key. Green CI confirms it.

3. An escaped ‌ became a literal zero-width non-joiner in a transformation's description. A hexdump shows 60 e2 80 8c here where main has the ‌ escape. Equivalent to any JSON parser, but it puts an invisible character into source that used to be self-documenting, and it reads like a reserialization artifact. I would restore the escape.

Two follow-ups, not blockers

1. applyToCode is a partial fix. rpai survives in inline code spans, which are still protected: `rpai auth token` in rpk-ai-run-claude.adoc and rpk-ai-run-codex.adoc, and `rpai agent a2a task get|watch|cancel` in rpk-ai-agent-a2a-send.adoc. Six occurrences across three partials, all published.

2. `rpk` ai appears 16 times and is untouched by this PR. The pipeline replaces rpai with plain rpk ai, and a later auto-backtick step then wraps only rpk, leaving backticks around half the command. It is visible on the published rpk ai run codex and rpk ai run claude pages, and it lives in the same transformation chain this PR is already editing, so it may be cheap to fix while you are in here.

What works well

• Fixing the rendered page alongside the override is the right call. The override alone would have left the duplicate heading live until the next regeneration.
• Merging the conditional lead-in into the section rather than deleting either copy preserves the behavior exactly: I rendered the page under Asciidoctor both ways and got one Example heading, the sample output in both builds, and the Quick Start pointer only when env-cloud is unset, with zero messages.
• The duplicate-heading warning added in Fix incorrect network id used in vpc-peering-aws.adoc #225 is what makes this class self-reporting from now on, and this is the second instance it has surfaced.
  EOF

[JakeSCahill]

@micheleRP this needs your approval to join the wave — it's the one PR in your merge sequence that still lacks one (mine, so I can't self-approve). It matters more than it looks now: it carries the applyToCode transformation rule plus its schema declaration, without which regenerated ai example blocks render rpai instead of rpk ai (visible in #1873's partials — transitional, and the post-#1862 auto-rerender fixes it once this is in). Ideally merges before #1862 so the final rerender wave carries the rule.

[JakeSCahill]

Thanks for making room for this in #1865 — all three points are now addressed:

• Undescribed scope: rewrote the PR body to describe all three changes (the Example fix, applyToCode, and the schema property).
• Flattened ‌ escape: restored on this branch (67ceb69). The same artifact had reached main through my earlier repair round-trip, so the fix that merged via Restore help content hidden by stale rpk description overrides #1862 restores it there too.
• The two follow-ups are fixed in doc-tools: Fix rpai in inline code spans and half-backticked command paths docs-extensions-and-macros#241 applies applyToCode rules to inline code spans (kills the six published rpai spans once this PR's flag lands) and wraps full multi-word command paths against the real command tree, which fixes all 16 `rpk` ai splits without heuristics.

Ready for another look when you are.

[JakeSCahill]

Sequencing note: please hold this merge until docs-extensions-and-macros#241 is released. #241 fixes the summary-generator defects that garbled two descriptions in #1875 (mid-token periods and unterminated paragraphs), and this PR's merge auto-triggers a rerender — with the current published doc-tools that rerender would revert the corrected pages on #1875 back to the garbled versions. Once 5.3.x with #241 is out, merging this heals everything in one pass: the applyToCode code blocks, the inline spans, and ~38 pages of run-on summaries.

[JakeSCahill]

@micheleRP doc-tools 5.3.3 is on npm with the #241 fixes, so the hold on this PR is lifted — it's ready for your re-review whenever suits. On merge, the auto-rerender now runs with the fixed generator: it reproduces main byte for byte plus this PR's applyToCode effect (rpai gone from code blocks and inline spans). That's the last docs piece of the train.