new-doc

new-doc

Create documentation pages with proper frontmatter, menu structure, and SEO optimization.

Core Principles

CRITICAL: Complete all 7 steps in sequence. Display progress as [Step X/7] before each step.

Important:

• Always display all 7 steps: Even when skipping a step, display it with an explanation (e.g., "[Step 2/7] Skipped - using suggested location from Step 1")
• Minimize open-ended questions: Use AskUserQuestion with prepopulated suggestions for nearly all inputs. Always provide smart defaults based on context.
• Store decisions: Track choices to avoid re-asking
• Check for existing docs first: Prevent duplication

Workflow Overview

1. [Step 1/7] Gather context, check existing docs, suggest page type/location
2. [Step 2/7] Confirm suggestions or navigate manually
3. [Step 3/7] Interactive directory navigation (if needed)
4. [Step 4/7] Gather content details (title, meta_desc, etc.)
5. [Step 5/7] Calculate menu weight
6. [Step 6/7] Generate menu metadata (identifier, parent; meta_image optional — generated if omitted)
7. [Step 7/7] Create file and validate

Steps

[Step 1/7] Gather Context and Check Existing Docs

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:

• Nearly identical topic: Existing page covers the same concept
• Related but distinct: Existing pages cover adjacent/related topics

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 update: Use Read to open the existing file, present to user, exit workflow
• If create: Continue with new page creation

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.

[Step 2/7] Confirm or Navigate

Always display this step, even if skipping.

Based on the user's response to the Step 1 question:

• "Use suggested location":

  • Display: "[Step 2/7] Confirmed - using suggested location: /docs/{path}"
  • Display: "[Step 3/7] Skipped - location already determined"
  • Store the suggested path and page type
  • Skip to Step 4 to gather content details

• "Choose different location":

  • Display: "[Step 2/7] User chose different location, proceeding to interactive navigation"
  • Proceed to Step 3 for interactive navigation

• "Let me refine my description":

  • Display: "[Step 2/7] User refining description"
  • Ask user for clarification, then re-run Step 1 analysis

Important: Page type (regular vs index) is already determined by this point. Don't ask again.

[Step 3/7] Interactive Navigation (if needed)

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:

• If number selected: Navigate into that subdirectory, repeat
• If "Place it here": Stop navigation
  • Regular pages: Create {slug}.md in current directory
  • Index pages: Create _index.md if it doesn't exist
• If "Enter path manually": Prompt for full path, validate, and use it
• If "Go up": Move to parent directory, repeat (handle root gracefully)

Continue navigation until placement is determined.

[Step 4/7] Gather Content Details

Gather all required metadata using AskUserQuestion with smart suggestions.

For regular pages, follow all patterns in new-doc:references:questions-regular:

1. Title (with Title Case suggestion)
2. Title tag (with "| Pulumi Docs" format)
3. Meta description (50-160 chars validation)
4. Filename (kebab-case validation)

For index pages, follow patterns in new-doc:references:questions-index:

• Part 1: Basic metadata (8 fields with smart suggestions)
  • Title, Link title, H1, Meta description, Description HTML
  • Primary button (label + link)
  • Secondary button (optional)
• Part 2: Sections array (iterative builder with card patterns)
  • Section type, heading, cards
  • Button cards, logo label cards, or flat text
  • Continue loop for multiple sections

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.

[Step 4b/7] Build Sections Array (Index 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:

1. Select section type (button-cards, cards-logo-label-link, or flat)
2. Gather section heading
3. If button-cards or cards-logo-label-link:
   • Determine card count (2-4 typical)
   • For each card: gather emoji/icon, heading, description, link
4. If flat: gather description paragraph
5. Ask if user wants to add another section

Validation: Ensure at least one section exists before proceeding to Step 5.

[Step 5/7] Calculate Menu Weight

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:

• No pages: suggest 10
• Pages exist: max weight rounded up to next multiple of 10
• Index pages: top-level suggest 1, subsection suggest 10+

Display result: "Calculated weight: {weight}"

[Step 6/7] Generate Menu Metadata

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:

• Regular pages: identifier of _index.md in same directory
• Top-level index: no parent
• Subsection index: identifier of parent directory's _index.md

Meta image: Optional. Leave meta_image blank and an on-brand social card is generated at build time. Only set it to override with a custom image (e.g. the cloud-specific docs images).

For override options: See new-doc:references:meta-images

Display result: "Menu identifier: {identifier}, Parent: {parent}, Meta image: {meta_image or 'generated'}"

[Step 7/7] Create File and Validate

Display: "[Step 7/7] Creating file and validating..."

Run validation checks from new-doc:references:validation:

• File doesn't exist
• Parent identifier exists
• Menu identifier unique
• Weight reasonable (0 < w < 1000)
• All required frontmatter present
• YAML valid
• Kebab-case filename (regular pages)
• Meta desc 50-160 chars
• Links valid (start with /docs/ or external)
• Verify the user is not committing to 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

Error Handling

For complete error handling strategies, see new-doc:references:validation (Error Handling section).

Common scenarios:

• File exists: Suggest alternatives or ask to overwrite
• Invalid filename: Auto-suggest kebab-case correction
• Missing parent: Warn about navigation issues, offer to create
• Duplicate identifier: Auto-append -2, -3 until unique
• Empty sections (index pages): Require at least one section before proceeding