@redpanda-data/docs-extensions-and-macros 4.13.0 → 4.13.1

package/mcp/prompts/README.adoc

@@ -0,0 +1,183 @@
+= MCP Server Prompts
+
+This directory contains prompt files for the Redpanda Docs MCP Server. Prompts provide contextual guides and instructions to LLMs when working with specific documentation tasks.
+
+== What are prompts?
+
+MCP Prompts are pre-defined instructions that LLMs can access when needed. They provide:
+
+* Detailed context about complex workflows
+* Rules and best practices
+* Step-by-step instructions
+* Quality checks and validation
+
+== How prompts work
+
+. **Writer makes a request**: "Improve the description for cleanup.policy"
+. **Claude detects the topic**: Recognizes this is about property documentation
+. **Retrieves the prompt**: Automatically loads `property-docs-guide.md`
+. **Follows instructions**: Updates overrides correctly, uses proper workflow
+. **Ensures quality**: Applies all rules and validation checks
+
+== Available prompts
+
+=== property-docs-guide.md
+
+**Purpose**: Comprehensive guide for updating Redpanda property documentation
+
+**When used**: Automatically retrieved when working with configuration properties
+
+**Key content**:
+
+* Override system explanation
+* Mandatory rules (no cloud conditionals, no enterprise includes)
+* Workflow instructions (update property-overrides.json, use generate_property_docs tool)
+* Common scenarios and examples
+* Validation steps
+
+=== rpcn-connector-docs-guide.md
+
+**Purpose**: Comprehensive guide for updating Redpanda Connect connector reference documentation
+
+**When used**: Automatically retrieved when working with connector documentation
+
+**Key content**:
+
+* Override system with `$ref` syntax explanation
+* DRY (Don't Repeat Yourself) principles
+* Repository structure and folder organization
+* Workflow instructions (update overrides.json, use generate_rpcn_connector_docs tool)
+* Quality checks and validation
+* Examples of `$ref` usage
+
+== Adding new prompts
+
+The MCP server uses automatic prompt discovery. No code editing required!
+
+=== 1. Create the markdown file
+
+Create a new file in this directory:
+
+[,bash]
+----
+prompts/your-prompt-name.md
+----
+
+=== 2. Add YAML frontmatter
+
+At the top of your file, add metadata:
+
+[,markdown]
+----
+---
+description: "Brief description for LLM to understand when to use this"
+version: "1.0.0"
+arguments:
+  content:
+    description: "The content to process (if needed)"
+    required: true
+---
+
+# Your Prompt Title
+
+This guide explains how to...
+
+## Your workflow:
+1. Do this
+2. Then do that
+3. Use the `tool_name` MCP tool to...
+
+## Rules you must follow:
+- Never do X
+- Always do Y
+----
+
+Required frontmatter fields:
+- description: What the prompt does
+- version: Semantic version (1.0.0)
+- arguments: (optional) Input parameters
+
+=== 3. Validate the prompt
+
+Check for errors:
+
+[,bash]
+----
+npx doc-tools validate-mcp
+----
+
+=== 4. Test it
+
+Restart Claude Code and test:
+
+[,text]
+----
+You: "List available prompts"
+Claude: *shows your new prompt*
+
+You: "Use the your-prompt-name prompt"
+Claude: *loads and follows your instructions*
+----
+
+== Writing good prompts
+
+**Do:**
+
+* **Write for LLMs**: Instructions should be direct ("You should..." not "Tell the user to...")
+* **Be specific**: Clear, actionable steps
+* **Include examples**: Show the correct way to do things
+* **Define rules**: List what must/must not be done
+* **Provide context**: Explain why rules exist
+* **Use workflow sections**: Step-by-step instructions
+
+**Don't:**
+
+* **Don't write for users**: Prompts are consumed by LLMs
+* **Don't be vague**: "Handle it appropriately" is not helpful
+* **Don't skip validation**: Always include quality checks
+* **Don't forget edge cases**: Cover error scenarios
+* **Don't embed in code**: Keep content in .md files
+
+== Prompt structure template
+
+[,markdown]
+----
+# Title - What This Prompt Does
+
+Brief explanation of the purpose.
+
+## Overview
+
+Context about the system/workflow.
+
+## Critical Rules (MANDATORY)
+
+- Never do X
+- Always do Y
+- Must include Z
+
+## Your workflow:
+
+1. First step
+2. Second step
+3. Use the `tool_name` MCP tool to...
+4. Validate the result
+
+## Common scenarios
+
+### Scenario 1: Description
+Steps to handle this case.
+
+### Scenario 2: Description
+Steps to handle this case.
+
+## Quality checks you must perform:
+
+- Check for A
+- Verify B
+- Ensure C
+
+## Validation
+
+How to verify everything worked correctly.
+----

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

@@ -0,0 +1,283 @@
+---
+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

@@ -0,0 +1,128 @@
+---
+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.