@redpanda-data/docs-extensions-and-macros 5.11.1 → 5.12.0

package/docs-data/rpk-overrides.schema.json

@@ -0,0 +1,744 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://redpanda.com/schemas/rpk-overrides.json",
+  "title": "RPK Documentation Overrides",
+  "description": "Schema for overriding auto-generated rpk command documentation. Provides comprehensive controls for technical writers to customize, exclude, deprecate, and enhance command documentation.",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Reference to this schema file"
+    },
+    "textTransformations": {
+      "type": "object",
+      "description": "Global text transformation rules applied to all command descriptions during generation. Allows writers to define patterns that should be formatted as inline code or replaced consistently across all commands.",
+      "properties": {
+        "replacements": {
+          "type": "array",
+          "description": "Text replacements applied BEFORE inline code formatting. Use for normalizing text (e.g., STDOUT → stdout). Applied in order.",
+          "items": {
+            "type": "object",
+            "properties": {
+              "pattern": {
+                "type": "string",
+                "description": "Regular expression pattern to match text that should be replaced. Use JavaScript regex syntax."
+              },
+              "replacement": {
+                "type": "string",
+                "description": "Replacement text. Can use $1, $2, etc. for capture groups, or $& for entire match."
+              },
+              "description": {
+                "type": "string",
+                "description": "Human-readable explanation of what this transformation does"
+              },
+              "flags": {
+                "type": "string",
+                "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 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"],
+            "additionalProperties": false
+          }
+        },
+        "inlineCode": {
+          "type": "array",
+          "description": "Patterns to wrap in inline code (backticks). Applied AFTER replacements and AFTER code block protection. Use negative lookbehind/lookahead to avoid double-wrapping.",
+          "items": {
+            "oneOf": [
+              {
+                "type": "string",
+                "description": "Regular expression pattern. Matched text will be wrapped in backticks."
+              },
+              {
+                "type": "object",
+                "properties": {
+                  "pattern": {
+                    "type": "string",
+                    "description": "Regular expression pattern to match text that should be wrapped in backticks"
+                  },
+                  "replacement": {
+                    "type": "string",
+                    "description": "Optional custom replacement (e.g., '`$1`' for first capture group). If omitted, wraps entire match in backticks."
+                  },
+                  "description": {
+                    "type": "string",
+                    "description": "Human-readable explanation of what this pattern matches"
+                  },
+                  "flags": {
+                    "type": "string",
+                    "description": "Regular expression flags. Default: 'g'",
+                    "default": "g",
+                    "pattern": "^[gimsuvy]*$"
+                  }
+                },
+                "required": ["pattern"],
+                "additionalProperties": false
+              }
+            ]
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "definitions": {
+      "type": "object",
+      "description": "Reusable definitions that can be referenced via $ref",
+      "additionalProperties": {
+        "$ref": "#/$defs/flagOverrides"
+      }
+    },
+    "commands": {
+      "type": "object",
+      "description": "Command-specific overrides, keyed by full command path (e.g., 'rpk topic create')",
+      "additionalProperties": {
+        "$ref": "#/$defs/commandOverride"
+      }
+    }
+  },
+  "$defs": {
+    "commandOverride": {
+      "type": "object",
+      "description": "Overrides for a specific command",
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "Override the command description. Replaces only the main description; sections from rpk output are preserved."
+        },
+        "appendToDescription": {
+          "type": "string",
+          "description": "Content to append to the auto-generated description instead of replacing it."
+        },
+        "descriptionScope": {
+          "type": "string",
+          "enum": ["cloud", "self-hosted", "both"],
+          "description": "Scope for the description override: 'cloud' (only in cloud docs), 'self-hosted' (only in self-hosted docs), or 'both' (default)"
+        },
+        "introducedInVersion": {
+          "type": "string",
+          "description": "Version when this command was introduced (e.g., 'v26.2.0')"
+        },
+        "flags": {
+          "$ref": "#/$defs/flagOverrides"
+        },
+        "$refs": {
+          "type": "array",
+          "description": "Array of $ref paths to merge into this command (e.g., ['#/definitions/common-kafka-flags'])",
+          "items": {
+            "type": "string"
+          }
+        },
+        "exclude": {
+          "type": "boolean",
+          "description": "If true, exclude this command from documentation entirely. Use for internal or hidden commands that shouldn't be documented."
+        },
+        "excludeFlags": {
+          "type": "array",
+          "description": "List of flag names to exclude from documentation (without dashes)",
+          "items": {
+            "type": "string"
+          }
+        },
+        "excludeExamples": {
+          "type": "array",
+          "description": "List of regex patterns to exclude specific examples from the source EXAMPLES section. Matches against example descriptions or commands.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "deprecated": {
+          "type": "boolean",
+          "description": "Mark this command as deprecated. A deprecation notice will be shown."
+        },
+        "deprecatedMessage": {
+          "type": "string",
+          "description": "Custom deprecation message explaining what to use instead. Only used when deprecated is true."
+        },
+        "deprecatedInVersion": {
+          "type": "string",
+          "description": "Version when this command was deprecated (e.g., 'v26.1.0')"
+        },
+        "removedInVersion": {
+          "type": "string",
+          "description": "Version when this command will be or was removed (e.g., 'v27.0.0')"
+        },
+        "replacement": {
+          "type": "string",
+          "description": "For deprecated commands, specify what command or approach to use instead. This is displayed in the deprecation notice."
+        },
+        "minVersion": {
+          "type": "string",
+          "description": "Minimum rpk version required for this command (e.g., 'v25.3.0')"
+        },
+        "platforms": {
+          "type": "array",
+          "description": "Platforms where this command is available. If not specified, assumed available on all platforms.",
+          "items": {
+            "type": "string",
+            "enum": ["linux", "darwin", "windows"]
+          }
+        },
+        "prerequisites": {
+          "type": "array",
+          "description": "Prerequisites or requirements before using this command",
+          "items": {
+            "type": "string"
+          }
+        },
+        "seeAlso": {
+          "type": "array",
+          "description": "Related commands or documentation pages. Can be strings (always shown) or objects with cloudOnly/selfHostedOnly properties for platform-specific links.",
+          "items": {
+            "oneOf": [
+              {
+                "type": "string",
+                "description": "xref link or command name (shown on all platforms)"
+              },
+              {
+                "type": "object",
+                "description": "Conditional see-also item shown only on specific platforms",
+                "properties": {
+                  "content": {
+                    "type": "string",
+                    "description": "The xref link or command name"
+                  },
+                  "cloudOnly": {
+                    "type": "boolean",
+                    "description": "If true, only shown in cloud docs (wrapped with ifdef::env-cloud[])"
+                  },
+                  "selfHostedOnly": {
+                    "type": "boolean",
+                    "description": "If true, only shown in self-hosted docs (wrapped with ifndef::env-cloud[])"
+                  }
+                },
+                "required": ["content"],
+                "additionalProperties": false,
+                "oneOf": [
+                  {
+                    "required": ["cloudOnly"],
+                    "not": { "required": ["selfHostedOnly"] }
+                  },
+                  {
+                    "required": ["selfHostedOnly"],
+                    "not": { "required": ["cloudOnly"] }
+                  }
+                ]
+              }
+            ]
+          }
+        },
+        "aliases": {
+          "type": "array",
+          "description": "Override or add command aliases",
+          "items": {
+            "type": "string"
+          }
+        },
+        "excludeAliases": {
+          "type": "array",
+          "description": "List of alias names to exclude from documentation (e.g., intentional misspellings for autocorrect)",
+          "items": {
+            "type": "string"
+          }
+        },
+        "aliasNotes": {
+          "type": "string",
+          "description": "A note to display after the aliases section explaining non-obvious aliases (e.g., autocorrect aliases)"
+        },
+        "content": {
+          "type": "array",
+          "description": "Unified content additions. Use this for all custom content (sections, cloud-only, self-hosted, admonitions, includes). Each item has: type, position, and type-specific fields.",
+          "items": {
+            "$ref": "#/$defs/contentItem"
+          }
+        },
+        "pageAliases": {
+          "type": "string",
+          "description": "Comma-separated list of page aliases for backwards compatibility. Preserves old URLs when commands are renamed. Example: 'reference:rpk/old-name.adoc, features:guide.adoc'"
+        },
+        "pageAttributes": {
+          "type": "object",
+          "description": "Custom page attributes to add to the header (e.g., page-topic-type, learning-objective-*)",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "cloudOnly": {
+          "type": "boolean",
+          "description": "If true, this command only appears in cloud documentation (entire page wrapped in ifdef::env-cloud[])"
+        },
+        "selfHostedOnly": {
+          "type": "boolean",
+          "description": "If true, this command only appears in self-hosted documentation (entire page wrapped in ifndef::env-cloud[])"
+        },
+        "_note": {
+          "type": "string",
+          "description": "Internal note for writers. Not used in documentation generation. Use for explaining override rationale or tracking issues."
+        }
+      },
+      "additionalProperties": false
+    },
+    "flagOverrides": {
+      "type": "object",
+      "description": "Flag-specific overrides, keyed by flag name (without dashes)",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string",
+            "description": "Override the flag description"
+          },
+          "type": {
+            "type": "string",
+            "description": "Override the flag type display"
+          },
+          "deprecated": {
+            "type": "boolean",
+            "description": "Mark this flag as deprecated"
+          },
+          "deprecatedMessage": {
+            "type": "string",
+            "description": "Custom deprecation message for the flag"
+          },
+          "required": {
+            "type": "boolean",
+            "description": "Override whether the flag is marked as required"
+          },
+          "default": {
+            "type": "string",
+            "description": "Override the displayed default value"
+          },
+          "validValues": {
+            "type": "array",
+            "description": "List of valid values for this flag (shown in docs)",
+            "items": {
+              "type": "string"
+            }
+          },
+          "cloudOnly": {
+            "type": "boolean",
+            "description": "Flag only available in cloud environment"
+          },
+          "selfHostedOnly": {
+            "type": "boolean",
+            "description": "Flag only available in self-hosted environment"
+          },
+          "introducedInVersion": {
+            "type": "string",
+            "description": "Version when this flag was introduced (e.g., 'v26.2.0'). Auto-populated by diff when new flags are detected."
+          }
+        }
+      }
+    },
+    "contentItem": {
+      "type": "object",
+      "description": "A content item to add to the documentation. The 'type' field determines what kind of content and which additional fields are required.",
+      "oneOf": [
+        {
+          "$ref": "#/$defs/contentItemSection"
+        },
+        {
+          "$ref": "#/$defs/contentItemExample"
+        },
+        {
+          "$ref": "#/$defs/contentItemExamples"
+        },
+        {
+          "$ref": "#/$defs/contentItemCloudOnly"
+        },
+        {
+          "$ref": "#/$defs/contentItemSelfHosted"
+        },
+        {
+          "$ref": "#/$defs/contentItemNote"
+        },
+        {
+          "$ref": "#/$defs/contentItemWarning"
+        },
+        {
+          "$ref": "#/$defs/contentItemTip"
+        },
+        {
+          "$ref": "#/$defs/contentItemCaution"
+        },
+        {
+          "$ref": "#/$defs/contentItemImportant"
+        },
+        {
+          "$ref": "#/$defs/contentItemInclude"
+        }
+      ]
+    },
+    "contentPosition": {
+      "type": "string",
+      "description": "Where to insert this content in the document",
+      "enum": [
+        "after_header",
+        "after_description",
+        "after_usage",
+        "after_aliases",
+        "after_flags",
+        "after_modifiers",
+        "after_examples",
+        "before_see_also",
+        "end"
+      ]
+    },
+    "contentItemSection": {
+      "type": "object",
+      "description": "A custom section with optional title. Supports subsections and parent sections with dynamic heading levels. If 'id' matches a source section (e.g., 'EXAMPLES', 'FIELDS'), you can: (1) use 'exclude: true' to remove it, or (2) provide 'content' to replace its content.",
+      "properties": {
+        "type": {
+          "const": "section"
+        },
+        "id": {
+          "type": "string",
+          "description": "Unique identifier for this section. If it matches a source section ID (e.g., 'EXAMPLES', 'FIELDS'), you can exclude or replace that section."
+        },
+        "title": {
+          "type": ["string", "null"],
+          "description": "Section title (e.g., 'Examples', 'Concept'). Use null for content without a section header."
+        },
+        "position": {
+          "$ref": "#/$defs/contentPosition"
+        },
+        "content": {
+          "type": "string",
+          "description": "Section content in AsciiDoc format. Omit if using subsections."
+        },
+        "subsections": {
+          "type": "array",
+          "description": "Array of nested subsections. Template automatically adjusts heading levels (=== for subsections, ==== for sub-subsections, etc.)",
+          "items": {
+            "$ref": "#/$defs/subsection"
+          }
+        },
+        "parent": {
+          "type": "string",
+          "description": "ID or lowercase title of an existing rpk section to nest this section inside. Template automatically adjusts heading levels. Example: 'flags' nests this section inside the Flags section."
+        },
+        "exclude": {
+          "type": "boolean",
+          "description": "If true, exclude a section from the rpk source output (use when overriding with custom content). The generator checks all case variations of the ID."
+        },
+        "headingLevel": {
+          "type": "integer",
+          "description": "Override the automatic heading level (2 for ==, 3 for ===, etc.). Use sparingly - template usually determines this automatically.",
+          "minimum": 2,
+          "maximum": 6
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": false,
+      "anyOf": [
+        {
+          "required": ["position"],
+          "description": "Normal section with position"
+        },
+        {
+          "required": ["exclude"],
+          "properties": {
+            "exclude": { "const": true }
+          },
+          "description": "Exclude-only section doesn't need position"
+        }
+      ]
+    },
+    "contentItemCloudOnly": {
+      "type": "object",
+      "description": "Content shown only in cloud docs (wrapped in ifdef::env-cloud[])",
+      "properties": {
+        "type": {
+          "const": "cloud-only"
+        },
+        "position": {
+          "$ref": "#/$defs/contentPosition"
+        },
+        "content": {
+          "type": "string",
+          "description": "Content in AsciiDoc format"
+        }
+      },
+      "required": ["type", "position", "content"],
+      "additionalProperties": false
+    },
+    "contentItemSelfHosted": {
+      "type": "object",
+      "description": "Content shown only in self-hosted docs (wrapped in ifndef::env-cloud[])",
+      "properties": {
+        "type": {
+          "const": "self-hosted"
+        },
+        "position": {
+          "$ref": "#/$defs/contentPosition"
+        },
+        "content": {
+          "type": "string",
+          "description": "Content in AsciiDoc format"
+        }
+      },
+      "required": ["type", "position", "content"],
+      "additionalProperties": false
+    },
+    "contentItemNote": {
+      "type": "object",
+      "description": "A NOTE admonition. Use plain text only - template automatically wraps in NOTE: or [NOTE]====...==== depending on complexity.",
+      "properties": {
+        "type": {
+          "const": "note"
+        },
+        "position": {
+          "$ref": "#/$defs/contentPosition"
+        },
+        "content": {
+          "type": "string",
+          "description": "Note content. Plain text with inline code/xrefs. Template detects complexity (includes, multiple paragraphs) and uses block format automatically."
+        }
+      },
+      "required": ["type", "position", "content"],
+      "additionalProperties": false
+    },
+    "contentItemWarning": {
+      "type": "object",
+      "description": "A WARNING admonition. Use plain text only - template automatically wraps in WARNING: or [WARNING]====...==== depending on complexity.",
+      "properties": {
+        "type": {
+          "const": "warning"
+        },
+        "position": {
+          "$ref": "#/$defs/contentPosition"
+        },
+        "content": {
+          "type": "string",
+          "description": "Warning content. Plain text with inline code/xrefs. Template detects complexity (includes, multiple paragraphs) and uses block format automatically."
+        }
+      },
+      "required": ["type", "position", "content"],
+      "additionalProperties": false
+    },
+    "contentItemTip": {
+      "type": "object",
+      "description": "A TIP admonition. Use plain text only - template automatically wraps in TIP: or [TIP]====...==== depending on complexity.",
+      "properties": {
+        "type": {
+          "const": "tip"
+        },
+        "position": {
+          "$ref": "#/$defs/contentPosition"
+        },
+        "content": {
+          "type": "string",
+          "description": "Tip content. Plain text with inline code/xrefs. Template detects complexity (includes, multiple paragraphs) and uses block format automatically."
+        }
+      },
+      "required": ["type", "position", "content"],
+      "additionalProperties": false
+    },
+    "contentItemCaution": {
+      "type": "object",
+      "description": "A CAUTION admonition. Use plain text only - template automatically wraps in CAUTION: or [CAUTION]====...==== depending on complexity.",
+      "properties": {
+        "type": {
+          "const": "caution"
+        },
+        "position": {
+          "$ref": "#/$defs/contentPosition"
+        },
+        "content": {
+          "type": "string",
+          "description": "Caution content. Plain text with inline code/xrefs. Template detects complexity (includes, multiple paragraphs) and uses block format automatically."
+        }
+      },
+      "required": ["type", "position", "content"],
+      "additionalProperties": false
+    },
+    "contentItemImportant": {
+      "type": "object",
+      "description": "An IMPORTANT admonition. Use plain text only - template automatically wraps in IMPORTANT: or [IMPORTANT]====...==== depending on complexity.",
+      "properties": {
+        "type": {
+          "const": "important"
+        },
+        "position": {
+          "$ref": "#/$defs/contentPosition"
+        },
+        "content": {
+          "type": "string",
+          "description": "Important content. Plain text with inline code/xrefs. Template detects complexity (includes, multiple paragraphs) and uses block format automatically."
+        }
+      },
+      "required": ["type", "position", "content"],
+      "additionalProperties": false
+    },
+    "contentItemInclude": {
+      "type": "object",
+      "description": "An include directive to add a partial or shared content",
+      "properties": {
+        "type": {
+          "const": "include"
+        },
+        "position": {
+          "$ref": "#/$defs/contentPosition"
+        },
+        "path": {
+          "type": "string",
+          "description": "Include path (e.g., 'shared:partial$warning-delete-records.adoc')"
+        },
+        "paths": {
+          "type": "array",
+          "description": "Multiple include paths",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "required": ["type", "position"],
+      "additionalProperties": false
+    },
+    "contentItemExample": {
+      "type": "object",
+      "description": "A single structured example. Writers provide plain text; template generates AsciiDoc code block automatically.",
+      "properties": {
+        "type": {
+          "const": "example"
+        },
+        "position": {
+          "$ref": "#/$defs/contentPosition"
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional description shown before the code block (plain text, inline code allowed)"
+        },
+        "code": {
+          "type": "string",
+          "description": "The code content. Template wraps in [,language]\\n----\\n...\\n----"
+        },
+        "language": {
+          "type": "string",
+          "description": "Code language (e.g., 'bash', 'json', 'yaml', 'text'). Defaults to 'bash'.",
+          "default": "bash"
+        },
+        "attributes": {
+          "type": "object",
+          "description": "Optional AsciiDoc block attributes (e.g., {\"role\": \"no-copy\"})",
+          "properties": {
+            "role": {
+              "type": "string"
+            },
+            "subs": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": true
+        }
+      },
+      "required": ["type", "position", "code"],
+      "additionalProperties": false
+    },
+    "contentItemExamples": {
+      "type": "object",
+      "description": "Multiple structured examples with optional section title. Template generates proper AsciiDoc section with code blocks.",
+      "properties": {
+        "type": {
+          "const": "examples"
+        },
+        "position": {
+          "$ref": "#/$defs/contentPosition"
+        },
+        "title": {
+          "type": "string",
+          "description": "Section title (e.g., 'Examples'). Defaults to 'Examples'.",
+          "default": "Examples"
+        },
+        "items": {
+          "type": "array",
+          "description": "Array of example items",
+          "items": {
+            "$ref": "#/$defs/exampleItem"
+          },
+          "minItems": 1
+        }
+      },
+      "required": ["type", "position", "items"],
+      "additionalProperties": false
+    },
+    "exampleItem": {
+      "type": "object",
+      "description": "A single example with description, code, and optional output",
+      "properties": {
+        "description": {
+          "type": "string",
+          "description": "Optional description for this example"
+        },
+        "code": {
+          "type": "string",
+          "description": "The code content"
+        },
+        "language": {
+          "type": "string",
+          "description": "Code language. Defaults to 'bash'.",
+          "default": "bash"
+        },
+        "output": {
+          "type": "string",
+          "description": "Optional expected output from running the command"
+        },
+        "outputLanguage": {
+          "type": "string",
+          "description": "Output block language. Defaults to 'bash'.",
+          "default": "bash"
+        },
+        "attributes": {
+          "type": "object",
+          "description": "Optional AsciiDoc block attributes",
+          "additionalProperties": true
+        }
+      },
+      "required": ["code"],
+      "additionalProperties": false
+    },
+    "subsection": {
+      "type": "object",
+      "description": "A subsection within a parent section. Template automatically determines heading level based on nesting depth. Use 'content' for AsciiDoc text or 'items' for structured examples.",
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "Subsection title"
+        },
+        "id": {
+          "type": "string",
+          "description": "Optional ID for this subsection (used for anchors)"
+        },
+        "content": {
+          "type": "string",
+          "description": "Subsection content in AsciiDoc format"
+        },
+        "items": {
+          "type": "array",
+          "description": "Structured examples with description, code, and optional output",
+          "items": {
+            "$ref": "#/$defs/exampleItem"
+          }
+        },
+        "subsections": {
+          "type": "array",
+          "description": "Nested subsections (can be nested arbitrarily deep)",
+          "items": {
+            "$ref": "#/$defs/subsection"
+          }
+        }
+      },
+      "required": ["title"],
+      "anyOf": [
+        { "required": ["content"] },
+        { "required": ["items"] }
+      ],
+      "additionalProperties": false
+    }
+  }
+}