| name | new-doc |
| description | Create Pulumi documentation with proper frontmatter and menu structure. |
Create documentation pages with proper frontmatter, menu structure, and SEO optimization.
CRITICAL: Complete all 7 steps in sequence. Display progress as [Step X/7] before each step.
Important:
Ask: What are you documenting?
Check for existing docs using Grep with key terms from user's description:
# Extract 2-3 key terms from user's description and search
grep -ri "key_terms" /workspaces/src/pulumi/docs/content/docs/ --include="*.md" | head -10
If existing docs found:
Analyze the results and categorize:
Then use AskUserQuestion:
# If nearly identical:
Question: "I found existing documentation on this topic at {path}. What would you like to do?"
Options:
- "Update existing page (Recommended)"
- "Create new page anyway"
# If related but distinct:
Question: "I found related documentation at {path1}, {path2}. What would you like to do?"
Options:
- "Create new page (Recommended)"
- "Update one of the existing pages"
Actions based on response:
If not found: Display "No existing documentation found. Proceeding with new page creation." and continue.
Suggest based on keywords - See new-doc:references:directory-hints for complete keyword mapping.
Present suggestions via AskUserQuestion:
Question: "I've analyzed your description. How would you like to proceed?"
Options:
- "Use suggested location (Recommended)"
- "Choose different location"
- "Let me refine my description"
Store choice. If "Use suggested location", skip to Step 4. Don't re-ask page type.
Always display this step, even if skipping.
Based on the user's response to the Step 1 question:
"Use suggested location":
"Choose different location":
"Let me refine my description":
Important: Page type (regular vs index) is already determined by this point. Don't ask again.
CRITICAL: Display locations by menu weight (NOT alphabetically) to match left-nav order.
bash .claude/commands/new-doc/scripts/list-directories.sh {path}
Display format:
Current location: docs > Infrastructure as Code
Available subsections:
1. Get Started (get-started)
2. Guides (guides)
3. Concepts (concepts)
...
Then ask via AskUserQuestion:
Question: "Where should this page be placed?"
Options:
- "1. Get Started (get-started)"
- "2. Guides (guides)"
- "3. Concepts (concepts)"
- "Place it here in current directory"
- "Enter path manually"
- "Go up one level"
Navigation flow:
{slug}.md in current directory_index.md if it doesn't existContinue navigation until placement is determined.
Gather all required metadata using AskUserQuestion with smart suggestions.
For regular pages, follow all patterns in new-doc:references:questions-regular:
For index pages, follow patterns in new-doc:references:questions-index:
Ask about content generation (regular pages only):
Question: "Should I generate a rough draft of the content?"
Options:
- "No, just create a stub with instructions (Recommended)"
- "Yes, generate a rough draft"
Store the choice. If "Yes", prepare to generate content in Step 7. If "No", use default stub template.
Then proceed to Step 4b for index pages, or Step 5 for regular pages.
For index pages only, build the sections array iteratively following the complete patterns in new-doc:references:questions-index (Part 2: sections array builder).
For each section:
Validation: Ensure at least one section exists before proceeding to Step 5.
Display: "[Step 5/7] Calculating menu weight..."
Find the maximum weight in the target directory:
# Find max weight in target directory
find {path} -name "*.md" -maxdepth 1 -exec grep -h "weight:" {} \; 2>/dev/null | grep -oE '[0-9]+' | sort -n | tail -1
Logic:
Display result: "Calculated weight: {weight}"
Display: "[Step 6/7] Generating menu metadata..."
Identifier: {section}-{subsection}-{slug} or {section}-{subsection}-home for index pages
Check uniqueness:
grep -rh "identifier:" /workspaces/src/pulumi/docs/content/docs/{section}/ | grep "{identifier}"
If conflict, append -2, -3, etc.
Parent:
Meta image: Use cloud-specific images for AWS, Azure, GCP, Kubernetes paths, default for others.
For complete mapping: See new-doc:references:meta-images
Display result: "Menu identifier: {identifier}, Parent: {parent}, Meta image: {meta_image}"
Display: "[Step 7/7] Creating file and validating..."
Run validation checks from new-doc:references:validation:
/docs/ or external)master directly (if so, warn them)Create file using templates from new-doc:references:frontmatter:
Regular pages: Use regular page template with title, title_tag, meta_desc, menu structure
If rough draft requested: Generate initial content sections based on the user's description and context
If stub only (default): Use this template after frontmatter:
## Overview
<!-- TODO: Add overview of this topic -->
## Prerequisites
<!-- TODO: List any prerequisites or requirements -->
## Next steps
<!-- TODO: Add links to related documentation or next steps -->
Index pages: Use index page template with sections array, link_buttons, docs_home flags (no additional content needed)
Display success output as defined in new-doc:references:validation:
✅ Created at /docs/{path}/{filename}.md
✅ Identifier: {identifier} (unique)
✅ Parent: {parent} (validated)
✅ Weight: {weight}
✅ Meta desc: {length} chars
Preview: http://localhost:1313/docs/{path}/
Next: Write content, run /docs-review, run make lint
For complete error handling strategies, see new-doc:references:validation (Error Handling section).
Common scenarios:
-2, -3 until uniqueReview docs and blog post quality before committing (style, accuracy, Pulumi best practices). Use when you've made content changes locally and want a quality pass on open files, the current branch, or a specific PR — outputs to the conversation, never posts to GitHub.
Generate a feature image (1884x1256) and OpenGraph meta image (1200x628) for a blog post. Reads the blog post title, selects a feature template (neo, platform, rocket, shield, lightbulb, or logo variant), renders feature.png, then composites it with title text onto meta.png. Use when the user types /blog-meta-image or asks to create, generate, or regenerate a blog post's feature image, meta image, social card, or Open Graph image. Accepts optional arguments like feature template name or logo names.