New Doc

New Doc

Scaffold a new MDX documentation page following all project conventions.

Required input from user

Ask for these before creating the file:

Optional (will generate defaults if not provided):

• sidebar_label — defaults to shortened title
• description — generate from title
• user_story — generate from content type and title

File creation

1. Determine file path

docs/{section}/{slug}.mdx

Slug: lowercase title, spaces to hyphens, no special chars. For ordered sections, check existing files for numeric prefixes (e.g., 01-, 02-) and use the next number.

2. Write frontmatter + skeleton

---
title: '{title}'
sidebar_label: '{sidebar_label}'
description: '{description}'
user_story: 'As a {role}, I want to {goal}'
content_type: '{content_type}'
author: '{author}'
sme: '{sme}'
---

{skeleton based on content_type}

3. Content type skeletons

how-to:

This how-to guide will help you {goal}.

## Prerequisites

- Item 1

## Steps

### Step 1: {first step}

{instructions}

### Step 2: {second step}

{instructions}

## Next steps

- [Related doc](link)

concept:

{One-paragraph summary of the concept.}

## Overview

{Detailed explanation}

## How it works

{Technical details}

## Key takeaways

- Point 1

quickstart:

This quickstart will get you {outcome} in under {time}.

## Prerequisites

- Item 1

## 1. {First step}

## 2. {Second step}

## What's next?

reference:

## Overview

{Brief description of what this reference covers.}

## Parameters

| Parameter | Type | Description |
| --------- | ---- | ----------- |
|           |      |             |

troubleshooting:

## Symptoms

{What the user observes}

## Common causes

### Cause 1: {description}

**Solution:** {fix}

4. Register in sidebar

Open sidebars.js and find the correct sidebar array for the section. Add the new doc ID (path relative to docs/ without extension):

'{section}/{slug}',

Place it in logical order within the existing items.

Terminology enforcement

Before writing any content, apply these substitutions:

Post-creation checklist

After creating the file:

1. Verify sidebar entry renders: yarn start --no-open and check navigation
2. Run yarn lint:markdown on the new file
3. Confirm no broken links: all [text](link) targets exist
4. If referencing globalVars, use @@variableName=value@@ syntax