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

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

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

package/mcp/prompts/write-new-guide.md

@@ -0,0 +1,222 @@
+---
+description: Generate a new tutorial or guide following team templates and style standards. Automatically applies approved terminology and voice/tone guidelines.
+version: 1.0.0
+arguments:
+  - name: topic
+    description: What the guide should teach (for example, "Configure TLS encryption", "Deploy a three-node cluster")
+    required: true
+  - name: audience
+    description: Target audience (for example, "beginners", "experienced developers", "operators")
+    required: false
+argumentFormat: structured
+---
+
+# Write New Documentation Prompt
+
+You are writing documentation for the Redpanda documentation team.
+
+## IMPORTANT: Fetch resources first
+
+**Before you begin writing**, you MUST:
+
+1. **Fetch the style guide**: Use the MCP `ReadResourceTool` or equivalent to read: `redpanda://style-guide`
+   - This contains complete style guide with Google Developer Documentation Style Guide principles
+   - You cannot write compliant documentation without this resource
+2. **Get Antora structure**: Use the `get_antora_structure` MCP tool to understand documentation organization
+
+**If you cannot access these resources, inform the user immediately.**
+
+## Additional resources to reference
+
+- Official glossary sources for terminology:
+  - GitHub: https://github.com/redpanda-data/docs/tree/shared/modules/terms/partials
+  - Published: https://docs.redpanda.com/current/reference/glossary/
+- `/lib` directory - Custom AsciiDoc macros and extensions documentation
+- `/extensions` directory - Custom Antora extensions
+
+## Documentation format
+
+We use **AsciiDoc** with **Antora**. Key formatting rules:
+
+### Cross-references (CRITICAL)
+
+Always include the module name in xrefs, even within the same component:
+
+Correct:
+```asciidoc
+xref:manage:kubernetes/configure-cluster.adoc[Configure your cluster]
+xref:reference:properties/cluster-properties.adoc[Cluster properties]
+```
+
+Never use:
+```asciidoc
+xref:./configure-cluster.adoc[...]  // No relative paths
+xref:configure-cluster.adoc[...]   // Missing module
+```
+
+### Glossary terms (CRITICAL)
+
+Use the `glossterm` macro for terms defined in the glossary (first mention in a document):
+
+Correct:
+```asciidoc
+A glossterm:topic[] is divided into glossterm:partition,partitions[]
+The glossterm:broker[] handles data replication
+Configure glossterm:TLS[] encryption for secure communication
+```
+
+Don't link terms manually:
+```asciidoc
+A xref:reference:glossary.adoc#topic[topic] is divided...  // Wrong syntax
+A topic is divided into partitions  // Not linked at all
+```
+
+**Glossary terms location**: https://github.com/redpanda-data/docs/tree/shared/modules/terms/partials
+
+### Code blocks
+
+Use custom roles for different code block types:
+
+**For commands:**
+```asciidoc
+[source,bash]
+----
+rpk topic create orders --partitions 3
+----
+```
+
+**For output (no copy button):**
+```asciidoc
+[source,bash,role=no-copy]
+----
+TOPIC    STATUS
+orders   OK
+----
+```
+
+**For long code (no wrapping, scrollbar instead):**
+```asciidoc
+[source,yaml,role=no-wrap]
+----
+very long configuration here...
+----
+```
+
+**For code with `<placeholder>` syntax (prevent frontend editing):**
+```asciidoc
+[source,bash,role=no-placeholders]
+----
+rpk topic create <topic-name>
+----
+```
+
+**Combine roles with comma:**
+```asciidoc
+[source,bash,role="no-copy,no-wrap"]
+----
+long output here...
+----
+```
+
+### Custom macros
+
+Check `/lib` and `/extensions` directories for available custom macros before writing. Use them appropriately.
+
+## Writing standards
+
+### Style (from Google Developer Documentation Style Guide)
+- Present tense
+- Active voice
+- Second person ("you")
+- **Sentence case for ALL headings except the title (H1)**
+  - H2, H3, H4, etc.: Only capitalize first word and proper nouns
+  - Example: "Configure TLS encryption" not "Configure TLS Encryption"
+- Clear, conversational tone
+- **Never use gerunds for instructions** (use imperative: "Create a topic" not "Creating a topic")
+
+### Redpanda-specific
+- Avoid overuse of bold text (only for UI elements, critical warnings)
+- Avoid em dashes (use parentheses or break into sentences)
+- Use realistic examples (no foo/bar placeholders)
+
+### Terminology
+Check the official glossary for approved terms:
+- GitHub: https://github.com/redpanda-data/docs/tree/shared/modules/terms/partials
+- Published: https://docs.redpanda.com/current/reference/glossary/
+
+Quick reference:
+- Product names: Redpanda, Redpanda Cloud, Redpanda Console, Redpanda Connect
+- Lowercase concepts: topic, partition, broker, cluster
+- Deprecated terms to avoid: master/slave, whitelist/blacklist, SSL (use TLS)
+
+## Page structure
+
+```asciidoc
+= Page Title
+:description: Brief description
+
+Opening paragraph explaining what this page covers.
+
+== First Section
+
+Content here.
+
+=== Subsection
+
+More content.
+```
+
+## Code example pattern
+
+Provide context, show the command, show the output:
+
+```asciidoc
+Create a topic for order events:
+
+[source,bash]
+----
+rpk topic create orders --partitions 3 --replicas 3
+----
+
+Expected output:
+
+[source,bash,role=no-copy]
+----
+TOPIC    STATUS
+orders   OK
+----
+```
+
+## Instructions format
+
+- Correct (imperative):
+- "Create a topic"
+- "Configure TLS"
+- "Deploy the cluster"
+
+- Incorrect (gerund):
+- "Creating a topic"
+- "Configuring TLS"
+- "Deploying the cluster"
+
+## Quality checklist
+
+- All xrefs include module name
+- Glossary terms use `glossterm` macro on first mention
+- Code blocks use appropriate roles (`.no-copy` for outputs)
+- Custom macros used correctly
+- Terminology follows approved dictionary
+- Voice is clear and conversational
+- No overuse of bold or em dashes
+- Present tense, active voice, second person
+- Imperative form for instructions (no gerunds)
+- Code examples are realistic and tested
+
+---
+
+Please provide:
+1. **Topic**: What to document
+2. **Type**: Tutorial, concept, reference, or guide
+3. **Target module** (optional): Where in Antora structure this belongs
+
+I'll create documentation following all team standards.

package/mcp/team-standards/style-guide.md

@@ -0,0 +1,321 @@
+# Redpanda Documentation Style Guide
+
+## Base Style Guide
+
+This guide is based on the [Google Developer Documentation Style Guide](https://developers.google.com/style). All Google style guidelines apply unless explicitly overridden below.
+
+Key Google style principles we emphasize:
+
+- Use present tense
+- Use active voice
+- Use second person ("you" instead of "the user")
+- Write in a conversational tone
+- Use sentence case for all headings except the page title
+
+## Redpanda team preferences
+
+### Formatting conventions
+
+Avoid overuse of bold text:
+- Use bold sparingly, primarily for UI elements and important warnings
+- Don't bold every important word or phrase
+- Prefer clear writing over heavy formatting
+- Good: "To enable TLS, set the `enable_tls` flag to true"
+- Avoid: "To **enable TLS**, set the **`enable_tls`** flag to **true**"
+
+Avoid em dashes:
+- Use parentheses or commas for asides instead of em dashes
+- Use colons to introduce explanations or lists
+- Break long sentences into shorter ones rather than using em dashes
+- Good: "TLS encryption (enabled by default) protects data in transit"
+- Good: "TLS encryption protects data in transit. It's enabled by default"
+- Avoid: "TLS encryption—enabled by default—protects data in transit"
+
+### When bold is appropriate
+
+Use bold only for:
+
+- UI element names: Click the Start button
+- Important warnings or cautions (sparingly)
+- Glossary terms on first use (optional, if using a glossary system)
+
+### When parentheses are better than em dashes
+
+Use parentheses for:
+
+- Clarifications or asides
+- Abbreviations: "Transport Layer Security (TLS)"
+- Version numbers or optional information
+
+## Redpanda-specific guidelines
+
+### Voice and tone
+
+General principles:
+
+- Clear and direct: Use simple, straightforward language
+- Technically accurate: Precision matters, but don't sacrifice clarity
+- Helpful: Anticipate questions and provide context
+- Conversational but professional: Friendly without being casual
+- Action-oriented: Focus on what users can do
+
+### Voice examples
+
+Good: "Configure your cluster to use TLS encryption for secure communication."
+Too Casual: "Let's slap some TLS on your cluster!"
+Too Formal: "It is advisable that one should configure the cluster such that TLS encryption protocols are employed."
+
+## Writing standards
+
+### Headings
+
+**Title (H1):** Can use title case or sentence case based on content type.
+
+**All other headings (H2, H3, H4, etc.):** Use sentence case only.
+
+- Capitalize only the first word and proper nouns
+- Make headings descriptive and scannable
+- Use verb phrases for task-based headings
+
+Examples:
+
+```asciidoc
+= Page Title Can Use Title Case (H1)
+
+== Configure TLS encryption (H2 - sentence case)
+
+=== Set up certificates (H3 - sentence case)
+
+== Deploy a three-node cluster (H2 - sentence case)
+```
+
+Good: "Configure TLS encryption"
+Good: "Deploy a three-node cluster"
+Bad: "Configure TLS Encryption" (don't capitalize "Encryption")
+Bad: "Deploy A Three-Node Cluster" (don't capitalize every word)
+Bad: "TLS" (not descriptive enough)
+Bad: "Configuration" (too vague)
+
+### Lists
+
+- Use parallel structure (all items start with same part of speech)
+- Use numbered lists for sequential steps
+- Use bulleted lists for non-sequential items
+- Capitalize the first word of each list item
+- Use periods for complete sentences, omit for fragments
+
+### Code examples
+- Always provide context before code examples
+- Include comments explaining non-obvious behavior
+- Show both the command and expected output when relevant
+- Use realistic examples, not foo/bar placeholders when possible
+
+### Links and cross-references
+
+We use AsciiDoc with Antora. Important rules:
+
+**Internal links (xref):**
+- Always include the module name, even within the same component
+- Never use relative paths (like `./page.adoc`)
+- Use descriptive link text (never "click here")
+
+```asciidoc
+Good: xref:security:tls-config.adoc[TLS configuration guide]
+Good: xref:manage:kubernetes/configure.adoc[Configure your cluster]
+Bad: xref:./tls-config.adoc[guide]  // No relative paths!
+Bad: xref:tls-config.adoc[guide]    // Missing module!
+Bad: xref:security:tls-config.adoc[Click here]  // Poor link text
+```
+
+**Glossary terms (glossterm macro):**
+- Use the `glossterm` macro to reference terms defined in the glossary
+- Link terms on first mention in a document
+- Glossary terms are in: https://github.com/redpanda-data/docs/tree/shared/modules/terms/partials
+
+```asciidoc
+✅ Good: A glossterm:topic[] is divided into glossterm:partition[,partitions]
+✅ Good: The glossterm:broker[] handles data storage
+❌ Bad: A topic is divided into partitions  // Terms not linked
+```
+
+**External links:**
+- Use descriptive link text
+- Include brief context for where the link goes
+
+```asciidoc
+✅ Good: See the https://kafka.apache.org/documentation/[Apache Kafka documentation]
+❌ Bad: See https://kafka.apache.org/documentation/[here]
+```
+
+## Structure standards
+
+### Prerequisites section
+Always include when users need:
+- Specific software installed
+- Prior configuration completed
+- Specific permissions or access
+- Understanding of certain concepts
+
+### Procedure format
+1. Start with what the user will accomplish
+2. List prerequisites
+3. Provide numbered steps
+4. Include verification steps
+5. Suggest next steps or related topics
+
+### Examples section
+Include examples that:
+- Cover common use cases
+- Show real-world scenarios
+- Include expected output
+- Explain what's happening
+
+## Terminology
+
+### Official glossary sources
+
+Our approved terminology is maintained in these locations:
+
+- **GitHub source**: https://github.com/redpanda-data/docs/tree/shared/modules/terms/partials (each term is a separate file)
+- **Published glossary**: https://docs.redpanda.com/current/reference/glossary/
+
+**Always reference the official glossary when you need term definitions or approved usage.**
+
+### Quick reference: Common terms
+
+Use these as a quick reference, but check the official glossary for complete definitions:
+
+**Product names:**
+- Redpanda (never RedPanda or red panda)
+- Redpanda Cloud
+- Redpanda Console
+- Redpanda Connect (formerly Benthos)
+- Kafka (when referring to Apache Kafka)
+
+**Kafka concepts (lowercase):**
+- topic
+- partition
+- broker
+- cluster
+- consumer
+- producer
+- leader (not master)
+- replica (not slave)
+
+**Security terms:**
+- TLS (not SSL - deprecated)
+- SASL
+- mTLS
+- ACL
+- allowlist (not whitelist - deprecated)
+- denylist (not blacklist - deprecated)
+
+**Command names (lowercase):**
+- `rpk`
+- `docker`
+- `kubectl`
+
+### Using the glossterm macro
+
+When writing documentation, link to glossary terms using the `glossterm` macro:
+
+```asciidoc
+A glossterm:topic[] is divided into glossterm:partition[,partitions]
+The glossterm:broker[] handles data replication
+```
+
+See the official glossary for the complete list of terms and their definitions.
+
+### Command documentation
+- Show the full command with all required flags
+- Explain what each flag does
+- Provide example output
+- Mention common errors and solutions
+
+### API documentation
+- Start with a one-sentence description
+- Document all parameters (name, type, required/optional, description)
+- Include request and response examples
+- Document error responses
+
+## Accessibility
+
+### Images and diagrams
+- Always include alt text
+- Use diagrams to supplement text, not replace it
+- Describe the diagram in surrounding text
+
+### Structure
+- Use proper heading hierarchy (don't skip levels)
+- One H1 per page
+- Logical heading progression (H2 → H3, never H2 → H4)
+
+### Code blocks
+- Always specify the language for syntax highlighting
+- Include descriptive titles when helpful
+- Ensure code is keyboard-navigable
+
+## Grammar and mechanics
+
+### Active voice
+Prefer active voice over passive voice for clarity.
+
+Good: "Redpanda encrypts data at rest"
+Avoid: "Data is encrypted at rest by Redpanda"
+
+### Present tense
+Use present tense for describing how things work.
+
+Good: "The broker replicates data across partitions"
+Avoid: "The broker will replicate data across partitions"
+
+### Second person
+Address the reader directly as "you".
+
+Good: "You can configure TLS by..."
+Avoid: "Users can configure TLS by..." or "We can configure TLS by..."
+
+### Contractions
+Use contractions sparingly in technical content. Avoid in:
+- Command documentation
+- API references
+- Configuration guides
+
+Acceptable in:
+- Tutorials
+- Conceptual overviews
+- Blog-style content
+
+## Error messages and troubleshooting
+
+### Format
+1. State what went wrong
+2. Explain why it happened
+3. Provide specific steps to fix it
+
+### Example
+
+```markdown
+**Problem**: `rpk` returns "connection refused"
+
+**Cause**: The Redpanda broker isn't running or isn't accessible on the specified port.
+
+**Solution**:
+1. Verify the broker is running: `systemctl status redpanda`
+2. Check the broker address: `rpk cluster info`
+3. Ensure no firewall is blocking port 9092
+```
+
+## Review checklist
+
+Before publishing, verify:
+- [ ] All code examples tested and working
+- [ ] Links are valid and point to correct destinations
+- [ ] Images have alt text
+- [ ] Headings follow hierarchy
+- [ ] Terminology is consistent and correct
+- [ ] Voice and tone are appropriate
+- [ ] Prerequisites are listed
+- [ ] Examples are realistic and helpful
+- [ ] Grammar and spelling are correct
+- [ ] Accessibility standards met