fix(rpk-ai): escape pipes in --format flag tables (fix 'dropping cells' table errors)#109
Conversation
…tables
The rpk-ai reference pages were generated 2026-06-10, before the rpk-docs
generator gained pipe-escaping (DOC-2220 / docs-extensions-and-macros#203,
2026-06-12). Their `--format` flag description contains a literal-pipe enum:
output format: table|wide|json|yaml|markdown
In an AsciiDoc table `|` is the cell delimiter, so each `|` in that value
opens a phantom cell and the row's cell count breaks, producing on every
affected page:
ERROR (asciidoctor): dropping cells from incomplete row detected end of table
This applies the same fix the current generator's escapePipes helper would
(`|` -> `{vbar}`) to the 36 affected pages. Surgical, content-preserving:
no command set changes, beta flags intact.
Note: a full regen from the rpk `dev` branch (the only ref with `rpk
--print-tree`) was evaluated but rejected as a drop-in — it pulls in ~34
unreleased rpk-ai commands and drops the intentional `:page-beta:` flags.
A proper full refresh against the GA rpai version + beta config is a
separate, owner-driven task.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
✅ Deploy Preview for redpanda-agentic-data-plane ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
micheleRP
left a comment
micheleRP
left a comment
There was a problem hiding this comment.
PR Review: fix(rpk-ai): escape pipes in --format flag tables (#109)
Files reviewed: 36 .adoc files (all auto-generated rpk-ai reference pages)
Overall assessment: Clean, correctly scoped bug fix, verified against the generator source. Approving. No critical issues, no blocking suggestions.
What this PR does
Escapes the literal | characters in the --format flag's enum value (table|wide|json|yaml|markdown) as {vbar} across 36 rpk-ai reference pages. In an AsciiDoc table an unescaped | is the cell delimiter, so each pipe opened a phantom cell, broke the row's cell count, and produced ~36 dropping cells from incomplete row asciidoctor errors in every build that aggregates adp-docs (including production). The change is one line per file.
Jira ticket alignment
No DOC-* key in the PR title, body, or branch. The body references DOC-2220 / docs-extensions-and-macros#203 as the generator fix that postdated these pages, but cites no ticket this PR itself closes. Not a blocker for a build-hygiene fix; link a tracking ticket if one exists.
Critical issues (must fix)
None.
Suggestions (should consider)
None that change the diff.
Verification performed
- Fix is correct at the source level. The generator's
escapePipes()helper (docs-extensions-and-macrostools/rpk-docs/helpers/index.js:405,|->{vbar}) is wired into the flag-description cell (templates/command.hbs:427), merged 2026-06-12 in #203, two days after these pages were generated (2026-06-10). So the hand-edit reproduces exactly what the current generator emits; it converges with generator output rather than diverging from it. - Complete blast radius.
{vbar}now appears in exactly these 36 files and nowhere else in the repo; zero literaltable|wide|jsonenums remain underrpk/. Sibling rpk pages (rpk-cloud, rpk-profile) don't expose--format, so there's no same-bug elsewhere. - No collateral changes. All 40
:page-beta:flags intact; no command-set or structural changes.
Generated-file / automation context
These are auto-generated pages, so the usual question is "should this go in an override?" Findings:
- No override path applies, now or soon. rpk doc generation (
generate_rpk_docs) takes onlytag/branch, no overrides file. A writer override system is ~1 week out (redpanda-data/docs#1733,docs-data/rpk-overrides.json), but it lives in the docs repo, not adp-docs, and explicitly excludesrpk ai(41 commands, "coming soon"). So there is no override the fix could live in. - The automation won't clobber this edit. Because rpk-ai is excluded from that workflow, an automated regen won't overwrite these files.
- Durable fix (future, owner-driven): a full rpk-ai regen against the GA rpai version with the correct beta/override config. That regen uses the fixed generator, so it reproduces
{vbar}, no conflict and no regression. A regen today is the wrong tool: the only ref with--print-treeis rpkdev, which pulls in ~34 unreleased commands and drops the:page-beta:flags.
Net: the hand-edit is the correct bridge until that regen happens.
Impact on other files
No impact detected. No pages added/renamed/moved, so nav.adoc, xrefs, What's New, and index/overview pages are all unaffected.
CodeRabbit findings worth considering
None, CodeRabbit has not posted on this PR.
What works well
- Genuinely surgical: one identical line-transform per file, nothing else touched.
- Correct fix,
{vbar}is the canonical AsciiDoc literal-pipe attribute and resolves properly in thea-spec description column; confirmed to match generator output. - Excellent PR description: root cause, the dated chain of events, why-not-full-regen, and the preserved-beta-flags guarantee are all spelled out and hold up under verification.
Reviewed against docs-team-standards.
|
cc: @JakeSCahill |
2 participants
Why
Every build that aggregates adp-docs logs ~36 of these:
Root cause: the rpk-ai pages were generated 2026-06-10, two days before the rpk-docs generator gained pipe-escaping (DOC-2220 / docs-extensions-and-macros#203, 2026-06-12). Their
--formatflag description holds a literal-pipe enum:In an AsciiDoc table,
|is the cell delimiter — so each pipe intable|wide|json|yaml|markdownopens a phantom cell, the row's cell count breaks, and the table errors at its closing delimiter. Non-fatal, but it's in every affected build's log (including production).What
Escape those pipes as
{vbar}(the AsciiDoc attribute for a literal pipe) — exactly what the current generator'sescapePipeshelper produces — across the 36 affected pages. One line changes per file:Surgical and content-preserving: no command-set changes,
:page-beta:flags intact.Why not a full regenerate
A full regen requires building rpk from the
devbranch (the only ref withrpk --print-tree). That output pulls in ~34 unreleased rpk-ai commands (a2a,agent credential,oauth-client dcr/iat,run claude/codex, …) and drops every:page-beta:flag — so it's not a safe drop-in. A proper full refresh against the GA rpai version with the correct beta/override config is a separate, owner-driven task (worth doing if those newer commands are in fact GA).🤖 Generated with Claude Code