next.js/.agents/skills/update-docs/references/DOC-CONVENTIONS.md

Next.js Documentation Conventions

Complete reference for frontmatter schema, code block formatting, and MDX component usage.

Frontmatter Schema

All MDX files must start with YAML frontmatter enclosed in --- delimiters.

Required Fields

Field	Description	Example
title	Page title for SEO and headings (2-3 words)	title: Image Component
description	Brief description (1-2 sentences)	description: Optimize images using next/image.

Optional Fields

Field	Description	Example
nav_title	Shorter title for navigation sidebar	nav_title: Image
source	Pull content from another page (avoid duplication)	source: app/api-reference/components/image
related	Next steps section with related links	See below
version	Development stage indicator	version: experimental

Related Links Format

---
title: My Feature
description: Description here.
related:
  title: Next Steps
  description: Learn more about related features.
  links:
    - app/api-reference/components/image
    - app/guides/optimizing/images
---

Version Field Values

• experimental - Experimental feature, may change
• legacy - Legacy feature, consider alternatives
• unstable - Unstable API, not recommended for production
• RC - Release candidate

Code Block Conventions

Basic Syntax

```language filename="path/to/file.ext"
code here
```

Required Attributes

Attribute	When to Use	Example
filename	Always for code examples	filename="app/page.tsx"
switcher	When providing TS and JS variants	switcher
highlight	To highlight specific lines	highlight={1,3-5}

TypeScript/JavaScript Switcher Pattern

Always provide TypeScript first, then JavaScript:

```tsx filename="app/page.tsx" switcher
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'My Page',
}
```

```jsx filename="app/page.js" switcher
export const metadata = {
  title: 'My Page',
}
```

Terminal Commands

Use bash language without filename:

```bash
npm install next
```

Highlighting Lines

highlight={1}        # Single line
highlight={1,3}      # Multiple lines
highlight={1-5}      # Range
highlight={1,3-5,8}  # Combined

MDX Components

AppOnly / PagesOnly

Use for router-specific content in shared documentation:

<AppOnly>

This content only appears in App Router documentation.

</AppOnly>

<PagesOnly>

This content only appears in Pages Router documentation.

</PagesOnly>

Important: Include blank lines inside the components for proper markdown parsing.

Image Component

For themed images with light/dark variants:

<Image
  alt="Description of the image"
  srcLight="/docs/light/image-name.png"
  srcDark="/docs/dark/image-name.png"
  width={1600}
  height={800}
/>

Notes and Callouts

Single line:

> **Good to know**: Important information here.

Multi-line:

> **Good to know**:
>
> - First point
> - Second point
> - Third point

Props Tables

Use HTML table wrapper for horizontal scroll on mobile:

<div style={{ overflowX: 'auto', width: '100%' }}>

| Prop              | Example             | Type    | Status   |
| ----------------- | ------------------- | ------- | -------- |
| [`src`](#src)     | `src="/image.png"`  | String  | Required |
| [`alt`](#alt)     | `alt="Description"` | String  | Required |
| [`width`](#width) | `width={500}`       | Integer | -        |

</div>

Status Values

• Required - Must be provided
• - - Optional
• Deprecated - Will be removed, use alternative

Shared Content Pattern

For Pages Router docs that share content with App Router:

App Router (source): docs/01-app/03-api-reference/02-components/image.mdx

• Contains the full documentation
• Uses <AppOnly> and <PagesOnly> for router-specific sections

Pages Router (consumer): docs/02-pages/03-api-reference/01-components/image.mdx

---
title: Image Component
description: Optimize images using next/image.
source: app/api-reference/components/image
---

The source field pulls content from the App Router doc.

Writing Style

Voice

• Guides: Instructional, use "you" to address users
• API Reference: Technical, use imperative verbs ("create", "pass", "return")

Clarity

• Use plain words over complex alternatives
• Be specific: "the src prop" not "this prop"
• Avoid jargon unless explaining it

Structure

Typical page structure:

1. Brief introduction (what and why)
2. Minimal working example
3. Detailed reference/options
4. Examples for different use cases
5. Related links (via frontmatter)

File Naming

• Use kebab-case: generate-metadata.mdx
• Add numeric prefix for ordering: 01-installation.mdx
• Index pages: index.mdx

Validation Commands

pnpm lint              # Full lint check
pnpm prettier-fix      # Fix formatting
pnpm types             # TypeScript check