Author a new documentation page

Help create a new documentation page that follows MetaMask editorial standards from the start.

When to use

• You need to scaffold a new page or write a first draft.
• You are helping someone who is not a writer produce content that meets team expectations.

Inputs

Ask the user for any information they have not already provided:

1. Product area - which product is this for? (MetaMask Connect, Embedded Wallets, Smart Accounts Kit, Agent Wallet, Snaps). Infura API and dashboard docs live at Infura documentation and are not authored in this repository.
2. Content type - what kind of page? (concept/explanation, how-to guide, quickstart, reference, tutorial, troubleshooting)
3. Topic - what is the page about?
4. File path - where should the file live? (Suggest one based on product and content type if the user doesn't specify.)

Step 1: Determine conventions

Based on the product and content type, load the relevant rules:

• .cursor/rules/content-types.mdc - structural expectations for the content type.
• .cursor/rules/product-*.mdc - product-specific terminology and conventions.
• .cursor/rules/editorial-voice.mdc - tone and voice.
• .cursor/rules/markdown-formatting.mdc - formatting conventions.
• .cursor/rules/terminology.mdc - required terms and casing.

Check how existing pages in the same folder are structured. Match their conventions for headings, front-matter fields, intro style, and parameter formats.

Step 2: Scaffold the page

Create the file with the correct structure for its content type.

Page metadata

Follow page metadata rules in .cursor/rules/markdown-formatting.mdc (required description, recommended keywords, optional sidebar_label only when the nav label would otherwise be too long or wordy, and the title vs duplicate H1 rule). Do not repeat or contradict that rule here.

Structure by content type

Concept / Explanation (for concepts/ or learn/ folders):

---
description: <one sentence>
---

# <Topic name>

<Opening paragraph: what this is and why it matters. 2-3 sentences. Get to the point.>

## <First concept section>

<Explain the concept. No step-by-step instructions.>

## <Second concept section>

...

## Next steps

- [<Related how-to guide>](<relative link>)
- [<Related reference>](<relative link>)

How-to guide (for guides/ or how-to/ folders):

---
description: <one sentence>
---

# <Action-oriented title: "Send a transaction" not "Sending transactions">

<Opening paragraph: what the reader will accomplish. 1-2 sentences.>

## Prerequisites

- <Requirement 1>
- <Requirement 2>

## Steps

### 1. <First action>

<Instruction. One action per step.>

### 2. <Second action>

...

## Next steps

- [<Related content>](link)

Quickstart (for quickstart/ or get-started/ folders):

---
description: <one sentence>
---

# <What the reader will build or achieve>

<Opening paragraph: what the reader will have at the end. 1-2 sentences.>

## Prerequisites

- <Requirement>

## Steps

### 1. <First step>

<Complete, copy-paste-ready code.>

### 2. <Second step>

...

## Next steps

- [<Extend this with a how-to guide>](link)

Reference (for reference/ folders):

---
description: <one sentence>
---

# <API or method name>

<One sentence describing what the method or API does.>

## Parameters

<Match the parameter format used in surrounding reference pages in the same product. Use tables
or nested bulleted lists depending on the established convention.>

## Returns

<Describe the return value.>

## Example

<Working code example.>

Tutorial (for tutorials/ folders):

---
description: <one sentence>
---

# <What the reader will learn>

<Opening paragraph: what the reader will build, what they will learn, and why it matters.
2-3 sentences.>

## Prerequisites

- <Requirement - assume no prior knowledge>

## Steps

### 1. <First step>

<Explain every step. Include expected output.>

...

## Complete code

<Full working code sample the reader can download or copy.>

## Next steps

- [<More advanced guide>](link)

Troubleshooting (for troubleshooting/ folders):

---
description: <one sentence>
---

# <Symptom or error message>

## Problem

<Describe the symptom. Include the exact error text if available.>

## Solution

<Steps to fix the issue.>

Step 3: Write the content

Fill in the scaffold with content based on what the user provides. Follow these rules:

• Voice: active, present tense, second person ("you"). Use contractions where appropriate.
• First sentence: get to the point. Answer "what" or "why" immediately.
• No em/en dashes: use commas, parentheses, or semicolons.
• Sentence case for all headings.
• One sentence per line, wrapped at about 100 columns.
• Code blocks: always include a language tag. Use bash npm2yarn for install commands.
• Terminology: use the required forms from terminology.mdc.
• No marketing language: no "powerful," "seamless," "best-in-class."
• No invented API behavior: if you are not certain about a parameter, return value, or behavior, add a :::note admonition flagging it for review rather than stating it as fact.

Step 4: Verify the file is complete

Before finishing, check:

• Page metadata includes description; add sidebar_label only when the default nav label would be too long or wordy (see markdown-formatting.mdc).
• Opening paragraph answers "what" and "why" in the first 1-2 sentences.
• Structure matches the content type.
• Terminology matches terminology.mdc and the product rule file.
• Code blocks have language tags.
• No em dashes, en dashes, or marketing language.
• File name uses lowercase and dashes (send-transactions.md, not sendTransactions.md).
• File is placed in the correct product and content-type folder.

Step 5: Remind the contributor

After creating the page, remind the user to:

1. Add the page to the correct sidebar file (see contributor-workflow.mdc for the mapping).
2. If any page was moved, renamed, or removed in the same change set, add redirects in vercel.json (see contributor-workflow.mdc).
3. Preview locally with npm start.
4. Check that the CI linter passes before requesting review.