Setting the file. One moment.
Subchapter 11.2
references/DOC-CONVENTIONS.mdMarkdown6 KBView on GitHub
Complete reference for frontmatter schema, code block formatting, and MDX component usage.
All MDX files must start with YAML frontmatter enclosed in --- delimiters.
| 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. |
| 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 |
---
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
---experimental - Experimental feature, may changelegacy - Legacy feature, consider alternativesunstable - Unstable API, not recommended for productionRC - Release candidate```language filename="path/to/file.ext"
code here
```| 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} |
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',
}
```Use bash language without filename:
```bash
npm install next
```highlight={1} # Single line
highlight={1,3} # Multiple lines
highlight={1-5} # Range
highlight={1,3-5,8} # CombinedUse 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.
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}
/>Single line:
> **Good to know**: Important information here.Multi-line:
> **Good to know**:
>
> - First point
> - Second point
> - Third pointUse 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>Required - Must be provided- - OptionalDeprecated - Will be removed, use alternativeFor Pages Router docs that share content with App Router:
App Router (source): docs/01-app/03-api-reference/02-components/image.mdx
<AppOnly> and <PagesOnly> for router-specific sectionsPages 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.
src prop” not “this prop”Typical page structure:
generate-metadata.mdx01-installation.mdxindex.mdxpnpm lint # Full lint check
pnpm prettier-fix # Fix formatting
pnpm types # TypeScript check