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

package/mcp/templates/README.adoc

@@ -0,0 +1,212 @@
+= MCP Extension Templates
+:toc:
+
+== Overview
+
+This directory contains ready-to-use templates for extending the MCP server. Copy these templates and customize them for your needs.
+
+== Available templates
+
+[cols="1,3"]
+|===
+|Template |Use For
+
+|`prompt-review-template.md`
+|Creating review prompts for specific content types
+
+|`prompt-write-template.md`
+|Creating writing prompts that generate new content
+
+|`resource-template.md`
+|Creating reference resources (guides, checklists, templates)
+|===
+
+== How to use these templates
+
+=== Quick start
+
+. Copy the template you need
+. Replace `[PLACEHOLDERS]` with your content
+. Add YAML frontmatter (for prompts)
+. Validate with `npx doc-tools validate-mcp`
+. Restart Claude Code and test
+
+=== Detailed steps
+
+**Step 1: Choose a template**
+
+Pick the template that matches what you're creating:
+- Review prompts → `prompt-review-template.md`
+- Writing prompts → `prompt-write-template.md`
+- Resources → `resource-template.md`
+
+**Step 2: Copy and rename**
+
+[source,bash]
+----
+# For a prompt
+cp mcp/templates/prompt-review-template.md mcp/prompts/review-api-docs.md
+
+# For a resource
+cp mcp/templates/resource-template.md mcp/team-standards/api-guide.md
+----
+
+**Step 3: Add frontmatter (prompts only)**
+
+Prompts need YAML frontmatter at the top. The templates include placeholder frontmatter - customize it:
+
+[source,yaml]
+----
+---
+description: "Your prompt description"
+version: "1.0.0"
+arguments:
+  content:
+    description: "The content to process"
+    required: true
+---
+----
+
+**Step 4: Customize the content**
+
+Replace all `[PLACEHOLDERS]` with your specific content:
+
+- `[CONTENT-TYPE]` → "API documentation", "troubleshooting guide", etc.
+- `[First thing to check]` → Specific checks for your use case
+- `[Section names]` → Appropriate section names
+
+**Step 5: Validate**
+
+Check your prompt or resource for errors:
+
+[source,bash]
+----
+npx doc-tools validate-mcp
+----
+
+**Step 6: Test**
+
+Restart Claude Code and test your new prompt or resource.
+
+No code editing required - the MCP server auto-discovers files in `mcp/prompts/` and `mcp/team-standards/`!
+
+== Customization tips
+
+=== For review prompts
+
+Focus on:
+- **Specific checks** relevant to the content type
+- **Common mistakes** you see in reviews
+- **Required elements** that must be present
+- **Output format** that's easy to act on
+
+Good checklist items:
+- Concrete and testable
+- Focused on one aspect
+- Clear about what success looks like
+
+=== For writing prompts
+
+Focus on:
+- **Clear structure** that matches your templates
+- **Specific requirements** for the content type
+- **Quality standards** that must be met
+- **Examples** showing what good looks like
+
+Good requirements:
+- Specific and actionable
+- Based on real patterns
+- Include rationale
+
+=== For resources
+
+Focus on:
+- **Practical examples** showing how to apply rules
+- **Good vs bad** comparisons
+- **Checklists** for quick verification
+- **Clear organization** that's easy to scan
+
+Good resources:
+- Scannable with clear headings
+- More examples than rules
+- Actionable guidance
+
+== Examples
+
+=== Example: Review prompt for API docs
+
+[source,bash]
+----
+# Copy template
+cp mcp/templates/prompt-review-template.md mcp/prompts/review-api-docs.md
+
+# Edit and customize
+vi mcp/prompts/review-api-docs.md
+----
+
+Key customizations:
+- Replace `[CONTENT-TYPE]` with "API documentation"
+- Add checks for: authentication section, request/response examples, error codes
+- Add common issues: missing status codes, unclear parameter descriptions
+- Define output format for API-specific feedback
+
+=== Example: Resource for code examples
+
+[source,bash]
+----
+# Copy template
+cp mcp/templates/resource-template.md mcp/team-standards/code-examples-guide.md
+
+# Edit and customize
+vi mcp/team-standards/code-examples-guide.md
+----
+
+Key customizations:
+- Add language-specific guidelines (bash, Python, YAML)
+- Include examples of good vs bad code formatting
+- Add checklist for code review
+- Show proper use of code block roles
+
+== Template placeholders reference
+
+Common placeholders you'll find in templates:
+
+[cols="1,2"]
+|===
+|Placeholder |Replace With
+
+|`[CONTENT-TYPE]`
+|Specific type: "API docs", "tutorials", "troubleshooting guides"
+
+|`[First thing to check]`
+|Specific checks relevant to your use case
+
+|`[Required section X]`
+|Sections that must be present
+
+|`[Resource Name]`
+|Name of your resource
+
+|`[Main Section X]`
+|Appropriate section names for your content
+
+|`[Check item X]`
+|Specific checklist items
+|===
+
+== Getting help
+
+- See link:../WRITER_EXTENSION_GUIDE.adoc[Writer Extension Guide] for complete instructions
+- Check existing prompts in `mcp/prompts/` for examples
+- Review existing resources in `mcp/team-standards/` for patterns
+- Ask your team lead for guidance
+
+== Contributing
+
+When you create a great prompt or resource:
+
+. Add it to the examples in link:../WRITER_EXTENSION_GUIDE.adoc[Writer Extension Guide]
+. Share it with the team
+. Consider if it should become a new template
+
+The more prompts and resources we build, the more consistent and efficient our docs team becomes!

package/mcp/templates/prompt-review-template.md

@@ -0,0 +1,80 @@
+---
+description: "Review [CONTENT-TYPE] for [specific aspects you're checking]"
+version: "1.0.0"
+arguments:
+  content:
+    description: "The [CONTENT-TYPE] content to review"
+    required: true
+---
+
+# Review [CONTENT-TYPE]
+
+You are reviewing [CONTENT-TYPE] for the Redpanda documentation team.
+
+## Your Task
+
+Review the provided content and check for:
+
+1. [First thing to check]
+2. [Second thing to check]
+3. [Third thing to check]
+4. [Additional checks...]
+
+## Resources to Reference
+
+Read these resources before reviewing:
+- `redpanda://style-guide` - Complete style guide
+- Official glossary for terminology:
+  - GitHub: https://github.com/redpanda-data/docs/tree/shared/modules/terms/partials
+  - Published: https://docs.redpanda.com/current/reference/glossary/
+- [Add other relevant resources]
+
+## Standards for [CONTENT-TYPE]
+
+[Describe what makes good content of this type]
+
+### Required Sections
+
+All [CONTENT-TYPE] documentation must include:
+- [Required section 1]
+- [Required section 2]
+- [Required section 3]
+
+### Format Requirements
+
+[Specific formatting rules for this content type]
+
+### Common Issues to Check
+
+- [Common mistake 1]
+- [Common mistake 2]
+- [Common mistake 3]
+
+## Output Format
+
+Provide a structured review:
+
+### Critical Issues (must fix)
+
+For each critical issue:
+- **Location**: [Section/paragraph reference]
+- **Issue**: [What's wrong]
+- **Fix**: [Specific correction]
+- **Reason**: [Why it matters]
+
+### Suggestions (should consider)
+
+For each suggestion:
+- **Location**: [Where it appears]
+- **Current**: [What it says now]
+- **Suggested**: [Better alternative]
+- **Reason**: [Why the suggestion helps]
+
+### Positive Elements
+
+What works well:
+- [Good thing 1]
+- [Good thing 2]
+- [Good thing 3]
+
+---

package/mcp/templates/prompt-write-template.md

@@ -0,0 +1,110 @@
+---
+description: "Generate [CONTENT-TYPE] following team standards"
+version: "1.0.0"
+arguments:
+  topic:
+    description: "The topic to write about"
+    required: true
+  target_module:
+    description: "Where in Antora structure this belongs (optional)"
+    required: false
+  context:
+    description: "Additional context or requirements"
+    required: false
+---
+
+# Write [CONTENT-TYPE]
+
+You are writing [CONTENT-TYPE] for the Redpanda documentation team.
+
+## Your Task
+
+Create [CONTENT-TYPE] that follows our team standards.
+
+## Resources to Read First
+
+- `redpanda://style-guide` - Complete style guide
+- Official glossary for terminology:
+  - GitHub: https://github.com/redpanda-data/docs/tree/shared/modules/terms/partials
+  - Published: https://docs.redpanda.com/current/reference/glossary/
+- `redpanda://[content-type]-template` - Template for this content type (if available)
+- [Add other relevant resources]
+
+Use `get_antora_structure` tool to understand the documentation organization.
+
+## Standards for [CONTENT-TYPE]
+
+### Structure
+
+[CONTENT-TYPE] should follow this structure:
+
+1. [Section 1]
+   - [What goes here]
+2. [Section 2]
+   - [What goes here]
+3. [Section 3]
+   - [What goes here]
+
+### Content Requirements
+
+[What must be included:]
+- [Requirement 1]
+- [Requirement 2]
+- [Requirement 3]
+
+### Writing Style
+
+Follow these style guidelines:
+- Present tense
+- Active voice
+- Second person ("you")
+- Sentence case for all headings except title
+- Imperative form for instructions (no gerunds)
+- Avoid overuse of bold or em dashes
+
+### AsciiDoc Format
+
+- All xrefs must include module name
+- Use `glossterm` macro for glossary terms on first mention
+- Code blocks use appropriate roles (`.no-copy` for outputs)
+- Custom macros used correctly
+
+## Quality Checklist
+
+Before finalizing, verify:
+- [ ] Structure follows template
+- [ ] All required sections included
+- [ ] Code examples are realistic and tested
+- [ ] Terminology uses approved terms
+- [ ] Glossary terms use `glossterm` macro
+- [ ] All xrefs include module names
+- [ ] Voice is clear and conversational
+- [ ] Headings use sentence case
+
+## Output Format
+
+Provide complete [CONTENT-TYPE] in AsciiDoc format:
+
+```asciidoc
+= Page Title
+:description: Brief description
+
+Opening content explaining what this covers.
+
+== First section
+
+Content here.
+
+== Second section
+
+More content.
+```
+
+---
+
+Please provide:
+1. **Topic**: What this [CONTENT-TYPE] should cover
+2. **Target module** (optional): Where in Antora structure this belongs
+3. **[Other context]**: [Additional information needed]
+
+I'll create complete [CONTENT-TYPE] following all team standards.

package/mcp/templates/resource-template.md

@@ -0,0 +1,76 @@
+# [Resource Name]
+
+[Brief description of what this resource provides]
+
+## Overview
+
+[1-2 paragraphs explaining when and how to use this resource]
+
+## [Main Section 1]
+
+[Content for this section]
+
+### Subsection
+
+[Details with examples]
+
+Example:
+
+```asciidoc
+[Example code or content here]
+```
+
+## [Main Section 2]
+
+[Content for this section]
+
+### Key Points
+
+- [Important point 1]
+- [Important point 2]
+- [Important point 3]
+
+### Examples
+
+Good:
+```
+[Good example]
+```
+
+Bad:
+```
+[Bad example - what to avoid]
+```
+
+## [Main Section 3]
+
+[Additional content]
+
+## Checklist
+
+Use this checklist to verify compliance:
+
+- [ ] [Check item 1]
+- [ ] [Check item 2]
+- [ ] [Check item 3]
+- [ ] [Check item 4]
+
+## Common Mistakes
+
+[List common mistakes and how to avoid them]
+
+### Mistake 1
+
+Problem: [What people do wrong]
+Solution: [How to do it right]
+
+### Mistake 2
+
+Problem: [What people do wrong]
+Solution: [How to do it right]
+
+## References
+
+- [Link to related resource 1]
+- [Link to related resource 2]
+- [Link to external documentation]

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@redpanda-data/docs-extensions-and-macros",
-  "version": "4.13.0",
+  "version": "4.13.1",
   "description": "Antora extensions and macros developed for Redpanda documentation.",
   "keywords": [
     "antora",
     "extension",
     "macro",
     "documentation",
-    "redpanda"
+    "redpanda",
+    "mcp"
   ],
   "author": {
     "name": "Redpanda Docs Team"
@@ -80,7 +81,8 @@
     "bin",
     "cli-utils",
     "tools",
-    "docker-compose"
+    "docker-compose",
+    "mcp"
   ],
   "license": "ISC",
   "repository": {