@redpanda-data/docs-extensions-and-macros 4.13.5 → 4.14.0

package/mcp/prompts/property-docs-guide.md

@@ -1,283 +0,0 @@
----
-description: Comprehensive guide for updating Redpanda property documentation using the override system. Explains how to work with auto-generated property files and the property-overrides.json system.
-version: 1.0.0
----
-
-# Property documentation update guide for LLMs
-
-This guide explains how to update Redpanda property documentation when all property reference pages are auto-generated.
-
-Critical rule: Never directly edit files in `/modules/reference/partials/properties/` - they are auto-generated and will be overwritten.
-
-## The auto-generation system
-
-All property documentation files are automatically generated from source code metadata.
-
-Generated files (do not edit):
-- `/modules/reference/partials/properties/broker-properties.adoc`
-- `/modules/reference/partials/properties/cluster-properties.adoc`
-- `/modules/reference/partials/properties/object-storage-properties.adoc`
-- `/modules/reference/partials/properties/topic-properties.adoc`
-
-Override file (edit this):
-- `/docs-data/property-overrides.json`
-
-## Why this matters
-
-When a user asks you to:
-- "Improve the description of cleanup.policy"
-- "Add an example for kafka_qdc_enable"
-- "Fix the documentation for compression.type"
-- "Add related topics to retention.ms"
-
-You must:
-1. Update `/docs-data/property-overrides.json`
-2. Run the doc-tools CLI to regenerate
-3. Do not edit the generated `.adoc` files directly
-
-## The override system
-
-The override file provides human-curated content that supplements or replaces auto-generated content.
-
-## File structure
-
-Location: `docs-data/property-overrides.json`
-
-Basic structure:
-```json
-{
-  "properties": {
-    "property_name": {
-      "description": "Enhanced description text",
-      "config_scope": "broker|cluster|topic",
-      "category": "category-name",
-      "example": [
-        "Line 1 of example",
-        "Line 2 of example"
-      ],
-      "related_topics": [
-        "xref:path/to/doc.adoc[Link Text]",
-        "xref:another/doc.adoc#anchor[Another Link]"
-      ],
-      "exclude_from_docs": false
-    }
-  }
-}
-```
-
-## What can be overridden
-
-Fields you can override:
-- `description` - Enhance or replace property description
-- `config_scope` - Specify broker/cluster/topic scope
-- `category` - Categorize property
-- `example` - Add YAML configuration examples (array of strings)
-- `related_topics` - Add cross-references (array of AsciiDoc xref links)
-- `exclude_from_docs` - Hide internal/deprecated properties
-- `type` - Override detected type
-- `default` - Override default value
-- `accepted_values` - Override accepted values
-
-## How to update overrides
-
-### Step 1: Read the current override file
-Always read the file first to preserve existing overrides.
-
-### Step 2: Add or update property overrides
-Modify the properties object.
-
-### Step 3: Write back to file
-Save the updated JSON.
-
-### Step 4: Verify JSON is valid
-Run: `python -c "import json; json.load(open('docs-data/property-overrides.json'))"`
-
-## Regenerating documentation
-
-### Prerequisites
-Before running doc-tools, you must have:
-1. A valid GitHub token with repo access to cloudv2 in the redpandadata organization
-2. The token set as the GITHUB_TOKEN environment variable
-
-### The doc-tools CLI
-After updating overrides, regenerate documentation:
-
-```bash
-npx doc-tools generate property-docs \
-  --tag "<redpanda-version>" \
-  --generate-partials \
-  --cloud-support \
-  --overrides docs-data/property-overrides.json
-```
-
-Important notes:
-- Always use `npx doc-tools` (not just `doc-tools`)
-- The `--tag` flag specifies which Redpanda version to generate docs for
-- The `--generate-partials` flag generates files in the partials directory
-- The `--cloud-support` flag must ALWAYS be included - never exclude it
-- The `--overrides` flag points to the property overrides JSON file
-
-## Property description rules (mandatory)
-
-### Never add enterprise license includes
-Do not include enterprise license markers in descriptions.
-
-Wrong:
-```
-Enable shadow linking for disaster recovery.
-
-include::reference:partial$enterprise-licensed-property.adoc[]
-```
-
-Right:
-```
-Enable shadow linking for disaster recovery.
-```
-
-Reason: Enterprise licensing information is displayed in the metadata table.
-
-### Never add descriptions for deprecated properties
-Do not add or update descriptions for properties marked as deprecated.
-
-Process:
-1. Check if the property is deprecated
-2. If deprecated, remove any existing override
-3. Never add new overrides for deprecated properties
-
-### Keep descriptions focused
-Descriptions should explain:
-- What the property does
-- When to use it
-- How it relates to other properties
-- Important behavioral details
-
-Descriptions should NOT include:
-- Version availability (metadata)
-- Cloud availability (metadata)
-- Enterprise license requirements (metadata)
-- Requires restart (metadata)
-- Default values (metadata)
-- Type information (metadata)
-
-### Use consistent formatting
-Use AsciiDoc formatting in descriptions:
-- `` `property_name` `` for property names
-- `xref:module:path/to/doc.adoc[Link Text]` for cross-references (always use full resource IDs with module prefix)
-- `<<anchor,text>>` for internal document references
-- `\n\n` for paragraph breaks
-
-Important: Always use full Antora resource IDs with module prefixes in xref links, never relative paths.
-
-Wrong:
-```json
-{
-  "description": "When `segment.bytes` is set, it overrides xref:./cluster-properties.adoc#log_segment_size[`log_segment_size`]."
-}
-```
-
-Right:
-```json
-{
-  "description": "When `segment.bytes` is set, it overrides xref:reference:properties/cluster-properties.adoc#log_segment_size[`log_segment_size`]."
-}
-```
-
-Common module prefixes:
-- `reference:` for reference documentation
-- `manage:` for management documentation
-- `deploy:` for deployment documentation
-- `get-started:` for getting started guides
-
-### Prefix self-managed-only links
-Some documentation pages only exist in self-managed deployments. Prefix these with `self-managed-only:`.
-
-Example:
-```json
-{
-  "kafka_connections_max": {
-    "related_topics": [
-      "self-managed-only:xref:manage:cluster-maintenance/configure-client-connections.adoc[Limit client connections]"
-    ]
-  }
-}
-```
-
-### Remove duplicate links
-Always remove duplicates from related_topics lists.
-
-### Normalize xref links to full resource IDs
-After updating overrides, normalize all xref links to use full Antora resource IDs.
-
-## Common scenarios
-
-### Improve a property description
-1. Read the override file
-2. Update the description field
-3. Write back to override file
-4. Use the `generate_property_docs` MCP tool to regenerate the documentation
-5. If that tool is not available, tell the user to run:
-   `npx doc-tools generate property-docs --tag "<version>" --generate-partials --cloud-support --overrides docs-data/property-overrides.json`
-
-### Add an example
-1. Add an `example` array with YAML lines to the property override
-2. Use the `generate_property_docs` MCP tool to regenerate
-
-### Add related topics
-1. Add `related_topics` array with AsciiDoc xref links
-2. Use the `generate_property_docs` MCP tool to regenerate
-
-### Fix incorrect metadata
-1. Override specific fields like `default` or `type`
-2. Use the `generate_property_docs` MCP tool to regenerate
-
-### Hide internal properties
-1. Set `exclude_from_docs: true`
-2. Use the `generate_property_docs` MCP tool to regenerate
-
-## Validation
-
-After updating overrides:
-1. Validate JSON syntax
-2. Check for common mistakes (example/related_topics are arrays, xref format)
-3. Verify after regeneration
-
-## Summary for LLMs
-
-When asked to update property documentation:
-
-1. Update `/docs-data/property-overrides.json`
-2. Run the doc-tools CLI with the correct command (including all required flags)
-3. Never edit `/modules/reference/partials/properties/*.adoc` directly
-
-Critical requirements:
-- Must have GITHUB_TOKEN environment variable set
-- Must ALWAYS include `--cloud-support` flag
-- Must use `npx doc-tools`
-- Must include all flags: `--tag`, `--generate-partials`, `--cloud-support`, `--overrides`
-
-Property description rules (mandatory):
-- Never add enterprise license includes
-- Never add descriptions for deprecated properties
-- Keep descriptions focused on behavior, not metadata
-- Use AsciiDoc formatting
-- Always use full Antora resource IDs with module prefixes in xref links
-- Prefix self-managed-only links with `self-managed-only:`
-- Remove duplicate links
-
-Your workflow:
-1. Always read the override file first to preserve existing overrides
-2. Make your changes to the property overrides
-3. Validate JSON syntax after changes
-4. Use the `generate_property_docs` MCP tool to regenerate the documentation
-   - Set version parameter to the Redpanda version
-   - Set generate_partials to true
-5. If the tool is not available, provide the user with the command:
-   `npx doc-tools generate property-docs --tag "<version>" --generate-partials --cloud-support --overrides docs-data/property-overrides.json`
-6. Explain what was changed and what files will be regenerated
-7. If generation fails, remind the user they need GITHUB_TOKEN set with cloudv2 repo access
-
-Quality checks you must perform:
-- Clean up any inappropriate content from descriptions (no enterprise includes, no cloud conditionals)
-- Remove any overrides for deprecated properties
-- Normalize all xref links to full Antora resource IDs with module prefixes
-- Remove duplicate links from related_topics arrays

package/mcp/prompts/review-for-style.md

@@ -1,128 +0,0 @@
----
-description: Review documentation content for style guide compliance, terminology consistency, and voice/tone. Provides detailed, actionable feedback based on team standards.
-version: 1.0.0
-arguments:
-  - name: content
-    description: The documentation content to review (can be a file path or raw content)
-    required: true
-argumentFormat: content-append
----
-
-# Style Review Prompt
-
-You are reviewing documentation for the Redpanda documentation team.
-
-## Your task
-
-Review the provided content against our style guide and provide detailed, actionable feedback on:
-
-1. **Style violations** with specific line/section references
-2. **Terminology issues** (incorrect terms, inconsistent usage, deprecated terms)
-3. **Voice and tone** feedback (too formal, too casual, inconsistent)
-4. **Structural issues** (missing sections, poor organization, heading hierarchy)
-5. **Formatting issues** (overuse of bold, em dashes, code formatting)
-6. **Accessibility issues** (missing alt text, poor heading structure)
-7. **Actionable fixes** for each issue found
-
-## IMPORTANT: Fetch the style guide first
-
-**Before you begin your review**, you MUST fetch the style guide resource:
-
-1. Use the MCP `ReadResourceTool` or equivalent to read: `redpanda://style-guide`
-2. This contains the complete Redpanda documentation style guide
-3. You cannot properly review without referencing this resource
-
-**If you cannot access the style guide resource, inform the user immediately.**
-
-**Terminology sources:**
-- GitHub: https://github.com/redpanda-data/docs/tree/shared/modules/terms/partials
-- Published glossary: https://docs.redpanda.com/current/reference/glossary/
-
-**Important**: Read the style guide before starting your review. Reference the official glossary for term definitions and usage.
-
-## Key style principles to check
-
-Based on Google Developer Documentation Style Guide:
-- Present tense for describing how things work
-- Active voice (not passive)
-- Second person ("you" not "the user")
-- **Sentence case for ALL headings except the title (H1)**
-  - Check that H2, H3, H4 only capitalize first word and proper nouns
-  - Example: "Configure TLS encryption" not "Configure TLS Encryption"
-- Clear, conversational tone
-
-Redpanda-specific preferences:
-- Avoid overuse of bold text (only for UI elements and important warnings)
-- Avoid em dashes (use parentheses or commas instead)
-- Use realistic examples (not foo/bar placeholders)
-- Proper product name capitalization (Redpanda, not RedPanda)
-
-## Terminology to verify
-
-Check for:
-- Correct product names (Redpanda, Redpanda Cloud, Redpanda Console, Redpanda Connect)
-- Lowercase concepts (topic, partition, broker, cluster, consumer, producer)
-- Deprecated terms (master/slave, whitelist/blacklist, SSL)
-- Consistent terminology throughout
-
-## Output format
-
-Provide your review in this structure:
-
-### Critical issues (must fix before publishing)
-
-For each critical issue:
-- **Location**: [Section/heading or line reference]
-- **Issue**: [What's wrong]
-- **Fix**: [Specific correction to make]
-- **Reason**: [Why it matters]
-
-### Style suggestions (should consider)
-
-For each suggestion:
-- **Location**: [Section/heading or line reference]
-- **Current**: [What it says now]
-- **Suggested**: [Better way to phrase it]
-- **Reason**: [Why the suggestion improves the content]
-
-### Terminology issues
-
-List all terminology problems:
-- **Incorrect term**: [What was used]
-- **Correct term**: [What should be used]
-- **Location**: [Where it appears]
-
-### Positive elements
-
-What works well in this content:
-- [List 2-3 things the author did well]
-- [Acknowledge good examples, clear explanations, proper structure, etc.]
-
-## Review guidelines
-
-- Be constructive and specific
-- Focus on high-impact improvements first
-- Acknowledge what's working well
-- Provide clear examples of fixes
-- Reference specific style guide sections when relevant
-- Don't just point out problems; explain why they matter
-- Consider the reader's experience
-
-## Example of good feedback
-
-- Poor feedback: "This section has style issues."
-
-- Good feedback:
-**Location**: Introduction, paragraph 2
-**Issue**: Uses passive voice - "Data is encrypted by Redpanda"
-**Fix**: "Redpanda encrypts data at rest"
-**Reason**: Active voice is clearer and more direct. Per our style guide, always prefer active voice for describing what software does.
-
-**Location**: Section heading
-**Issue**: Title case used for H2 heading - "Configure TLS Encryption"
-**Fix**: "Configure TLS encryption"
-**Reason**: All headings except the page title (H1) must use sentence case. Only capitalize the first word and proper nouns.
-
----
-
-Please provide the content you'd like me to review.

package/mcp/prompts/rpcn-connector-docs-guide.md

@@ -1,126 +0,0 @@
----
-description: Comprehensive guide for updating Redpanda Connect connector reference documentation using the overrides system with $ref syntax. Explains the DRY approach for connector documentation.
-version: 1.0.0
----
-
-# Redpanda Connect Reference Documentation: LLM Prompt Guide
-
-Redpanda Connect reference documentation is generated using a combination of:
-
-- **Autogenerated content**: Produced from source code and schemas, providing a baseline of all available fields, types, and options.
-- **Overrides**: A JSON file (`overrides.json`) that allows technical writers to override, deduplicate, clarify, and cross-reference field descriptions using a DRY (Don't Repeat Yourself) approach.
-
-## Repository folder structure
-
-- `/docs`: Built documentation site (HTML, assets, and static files for all Redpanda Connect docs versions)
-- `/docs-data`: Source data for reference docs, including `overrides.json` and autogenerated JSON files
-- `/modules`: Modular AsciiDoc content for guides, cookbooks, and reference topics
-- `/package.json`, `README.adoc`, `antora.yml`: Project configuration and metadata
-- `/.github`: GitHub workflows and Copilot custom instructions
-
-## `$ref` syntax
-
-- The `$ref` syntax is used in the overrides file to avoid repeating identical or similar descriptions for fields that appear in multiple places.
-- Instead of duplicating a description, a field can reference a central definition using:
-
-  ```json
-  "$ref": "#/definitions/field_name"
-  ```
-
-- The referenced definition is found in the `definitions` section at the top of `overrides.json`.
-- This approach ensures consistency, simplifies updates, and enables cross-referencing between related fields.
-
-## How reference docs are structured
-
-- **Autogenerated files** (such as `.adoc` or `.json`): List all fields, types, options, and sometimes examples, but may lack clarity, deduplication, or cross-references.
-- **Overrides file** (`overrides.json`):
-  - Contains a `definitions` section for reusable field descriptions.
-  - Uses `$ref` to point fields in the autogenerated structure to these definitions.
-  - Allows for cross-references between related fields (such as "see also", "must be used with", etc.).
-  - Supports enhancements for clarity, user-friendliness, and technical accuracy.
-
-## Example
-
-```json
-"definitions": {
-  "client_certs": {
-    "description": "A list of client certificates for mutual TLS (mTLS) authentication. ... (full description here)"
-  }
-},
-"inputs": [
-  {
-    "name": "amqp_0_9",
-    "config": {
-      "children": [
-        {
-          "name": "tls",
-          "$ref": "#/definitions/tls",
-          "children": [
-            {
-              "name": "client_certs",
-              "$ref": "#/definitions/client_certs"
-            }
-          ]
-        }
-      ]
-    }
-  }
-]
-```
-
-## Your workflow
-
-When asked to improve or work with Redpanda Connect reference documentation:
-
-1. **Read the overrides file**: Always start by reading `docs-data/overrides.json` to understand the current structure and definitions.
-
-2. **Understand the `$ref` system**: Do not duplicate descriptions; suggest improvements to central definitions and update references as needed.
-
-3. **Make improvements**:
-   - Suggest improvements for clarity, consistency, and user experience, especially in the `definitions` section
-   - Identify opportunities for new or improved cross-references between related fields
-   - Create new definition objects for missing references or enhance existing ones
-   - Recommend deduplication: If you find repeated inline descriptions, propose moving them to a definition and referencing them with `$ref`
-
-4. **Update the overrides file**: Use the Edit or Write tool to update `docs-data/overrides.json` with your changes.
-
-5. **Regenerate documentation**: Use the `generate_rpcn_connector_docs` MCP tool to regenerate the documentation with your changes.
-   - Default branch is "main"
-   - Can specify a different branch if needed
-
-6. **Explain your changes**: Provide a clear explanation of what you changed and why.
-
-## Quality checks you must perform
-
-- **Preserve technical accuracy**: Ensure that all field descriptions are correct, actionable, and user-friendly
-- **Maintain DRY principles**: Avoid unnecessary repetition in the documentation
-- **Validate JSON syntax**: Ensure the overrides file remains valid JSON after your changes
-- **Check $ref references**: Ensure all `$ref` references point to valid definitions
-- **Maintain consistency**: Use consistent terminology and formatting across all descriptions
-
-## Output expectations
-
-When asked for improvements, your output should include:
-
-- Suggested changes to the `definitions` section
-- Proposed new or updated `$ref` references
-- Rationale for changes (clarity, deduplication, cross-linking, etc.)
-- Any additional user experience or technical writing enhancements
-- Summary of what will be regenerated
-
-## Summary for LLMs
-
-When working with Redpanda Connect reference documentation:
-
-1. Read `docs-data/overrides.json` first to understand the current structure
-2. Make your improvements to the definitions and $ref references
-3. Update the overrides file using Edit or Write tool
-4. Use the `generate_rpcn_connector_docs` MCP tool to regenerate documentation
-5. Explain what was changed and why
-
-Critical requirements:
-- Always respect the `$ref` system - don't duplicate descriptions
-- Maintain DRY principles throughout
-- Validate JSON syntax after changes
-- Preserve technical accuracy
-- Ensure all `$ref` references are valid