Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/shuding/nextra/llms.txt

Use this file to discover all available pages before exploring further.

Nextra projects follow a set of well-defined file conventions that control how content is discovered, how navigation is structured, and how MDX elements are rendered. Understanding these conventions is the foundation for working effectively with any Nextra-powered site.

​
Conventions at a Glance

The four primary conventions you’ll encounter in every Nextra project are:
ConventionPurpose
content/ directoryThe default location for your .md and .mdx content files
page.mdx / page.mdNext.js App Router pages that Nextra processes directly
_meta.js filesConfigure sidebar order, titles, separators, and navigation menus
mdx-components fileOverride how standard Markdown elements (headings, links, images) are rendered
All of these can optionally live inside a src/ directory if you prefer to keep application code separate from project configuration files.

​
Content Files

content/ Directory

Store all your .md and .mdx files in the content/ directory. Nextra auto-discovers them and maps them to URL routes without needing the page filename convention.

page.mdx File

Use Next.js App Router’s page.mdx or page.md files when you need fine-grained control over routing or want to co-locate MDX content with other app directory files.

_meta.js File

Control sidebar order, page titles, external links, separators, and dropdown menus. Every directory can have its own _meta.js file.

mdx-components File

Export a useMDXComponents function to override how heading tags, anchors, images, and other HTML elements are rendered across all MDX pages.

​
Using a src/ Directory

Nextra supports the common convention of placing all application code — including the content/ directory and the mdx-components file — under a top-level src/ folder. This separates source code from project configuration files (such as next.config.mjs and package.json) that live at the project root. 
your-project/
├── src/
│   ├── app/
│   │   ├── layout.jsx
│   │   └── [[...mdxPath]]/
│   │       └── page.jsx
│   ├── content/
│   │   └── index.mdx
│   └── mdx-components.js
├── next.config.mjs
└── package.json
Nextra automatically detects whether your content/ directory lives at the project root or inside src/ by scanning for both content and src/content using the glob pattern {src/,}content. No additional configuration is needed.

​
Combining Approaches

You can mix the content/ directory approach with the app/ directory approach in the same project. Nextra collects .md and .mdx files from content/ and gathers page.md / page.mdx files from the app/ directory to build a unified pageMap used for navigation.
Routes defined in the app/ directory take precedence over same-named routes in content/. Plan your directory structure accordingly to avoid conflicts.

Build docs developers (and LLMs) love

Get started for freeTalk to us