# New Doc

> Create Pulumi documentation with proper frontmatter and menu structure. Use when this capability is needed.

- Skill: `tomevault-io/new-doc` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/new-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/new-doc/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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)
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:

```bash
# 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:

```text
# 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:**

```text
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
bash .claude/commands/new-doc/scripts/list-directories.sh {path}
```

**Display format:**

```text
Current location: docs > Infrastructure as Code

Available subsections:
1. Get Started (get-started)
2. Guides (guides)
3. Concepts (concepts)
...
```

**Then ask via AskUserQuestion:**

```text
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):**

```text
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:

```bash
# 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:**

```bash
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**: 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}"

### [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:

    ```markdown

    ## 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`:

```text
✅ 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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/pulumi) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->