From 82a8159b6cdde68ec7dc9288391e20c8ef22cfee Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Fri, 31 Jul 2026 09:58:34 +0100 Subject: [PATCH 1/5] fix: remove duplicate Example heading on rpk container status The override for rpk container status carried two content items that each emit a level-2 Example heading: a self-hosted item with the heading hard-coded in its content, and a section item titled Example. The rendered page shows the same section heading twice and the anchors collide. Merge the Quick Start lead-in (still wrapped in ifndef::env-cloud) into the Example section and apply the same fix to the rendered page. Verified against a full regeneration with doc-tools 5.3.0, which now also warns when a page renders duplicate headings. --- docs-data/rpk-overrides.json | 9 ++------- .../pages/rpk/rpk-container/rpk-container-status.adoc | 4 +--- 2 files changed, 3 insertions(+), 10 deletions(-) diff --git a/docs-data/rpk-overrides.json b/docs-data/rpk-overrides.json index 4ab4be0760..e8e5ea3bfb 100644 --- a/docs-data/rpk-overrides.json +++ b/docs-data/rpk-overrides.json @@ -338,7 +338,7 @@ "flags": "g" }, { - "description": "Wrap bare flag with adjacent format/value word as inline code before auto-backtick step splits them (e.g. -f json -> `\u200c-f json`, --format yaml -> `--format yaml`)", + "description": "Wrap bare flag with adjacent format/value word as inline code before auto-backtick step splits them (e.g. -f json -> `‌-f json`, --format yaml -> `--format yaml`)", "pattern": "(? Date: Fri, 31 Jul 2026 10:33:27 +0100 Subject: [PATCH 2/5] chore: mark the rpai binary-name rewrite as safe for code blocks doc-tools now captures help command examples into verbatim code blocks, where only textTransformations rules flagged applyToCode run. The rpai to rpk ai rewrite needs the flag so rpk ai command examples render with the command users actually type. --- docs-data/rpk-overrides.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs-data/rpk-overrides.json b/docs-data/rpk-overrides.json index e8e5ea3bfb..8aaa5576ac 100644 --- a/docs-data/rpk-overrides.json +++ b/docs-data/rpk-overrides.json @@ -323,7 +323,8 @@ "description": "Replace rpai shorthand with rpk ai in examples (rpai is the plugin binary name)", "pattern": "\\brpai\\b", "replacement": "rpk ai", - "flags": "g" + "flags": "g", + "applyToCode": true }, { "description": "Wrap Redpanda secret scope values in inline code", From 488521361c9a37baa9ed806962278edb88d5dff2 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Fri, 31 Jul 2026 10:38:18 +0100 Subject: [PATCH 3/5] chore: allow applyToCode in the overrides schema The rpai rewrite rule now carries applyToCode: true, which the sibling schema must permit or override validation reports the rule as invalid. --- docs-data/rpk-overrides.schema.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs-data/rpk-overrides.schema.json b/docs-data/rpk-overrides.schema.json index 8bfe96f2b6..263026e44e 100644 --- a/docs-data/rpk-overrides.schema.json +++ b/docs-data/rpk-overrides.schema.json @@ -36,6 +36,10 @@ "description": "Regular expression flags. Default: 'g' (global). Common: 'gi' (global, case-insensitive)", "default": "g", "pattern": "^[gimsuvy]*$" + }, + "applyToCode": { + "type": "boolean", + "description": "Also apply this replacement inside code blocks captured from help text (verbatim command examples). Default false: code blocks are protected from prose transformations. Use for binary-name rewrites like rpai to rpk ai." } }, "required": ["pattern", "replacement"], From 67ceb69bef49c1dfedc7c1d8478156863ef94161 Mon Sep 17 00:00:00 2001 From: JakeSCahill Date: Mon, 3 Aug 2026 09:45:44 +0100 Subject: [PATCH 4/5] Restore the zero-width non-joiner escape flattened by a json round-trip Review finding: the \u200c escape in a transformation description became a literal invisible character during reserialization. Restored (byte-identical semantics, readable source). --- docs-data/rpk-overrides.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-data/rpk-overrides.json b/docs-data/rpk-overrides.json index 8aaa5576ac..64cf57c632 100644 --- a/docs-data/rpk-overrides.json +++ b/docs-data/rpk-overrides.json @@ -339,7 +339,7 @@ "flags": "g" }, { - "description": "Wrap bare flag with adjacent format/value word as inline code before auto-backtick step splits them (e.g. -f json -> `‌-f json`, --format yaml -> `--format yaml`)", + "description": "Wrap bare flag with adjacent format/value word as inline code before auto-backtick step splits them (e.g. -f json -> `\u200c-f json`, --format yaml -> `--format yaml`)", "pattern": "(? Date: Mon, 3 Aug 2026 11:28:34 +0100 Subject: [PATCH 5/5] Match the doc-tools schema wording: applyToCode covers inline code spans too --- docs-data/rpk-overrides.schema.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-data/rpk-overrides.schema.json b/docs-data/rpk-overrides.schema.json index 263026e44e..3d97879fb0 100644 --- a/docs-data/rpk-overrides.schema.json +++ b/docs-data/rpk-overrides.schema.json @@ -39,7 +39,7 @@ }, "applyToCode": { "type": "boolean", - "description": "Also apply this replacement inside code blocks captured from help text (verbatim command examples). Default false: code blocks are protected from prose transformations. Use for binary-name rewrites like rpai to rpk ai." + "description": "Also apply this replacement inside code contexts: code blocks captured from help text (verbatim command examples) and inline code spans. Default false: code contexts are protected from prose transformations. Use for binary-name rewrites like rpai to rpk ai." } }, "required": ["pattern", "replacement"],