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.

The content/ directory is Nextra’s dedicated folder for Markdown and MDX content files. It lets you organize pages without following the page filename convention required by the Next.js App Router, making it an ideal home for documentation, blog posts, and other content-heavy sites.

​
Why Use the content/ Directory?

The content/ directory solves two common problems:
  • Migration from the Next.js pages router — Rename your existing pages/ directory to content/ and get up and running with minimal changes.
  • Cleaner file paths — Instead of app/configuration/page.mdx, you write content/configuration.mdx. The route stays the same; the file tree is much easier to navigate.

​
How Nextra Discovers Content Files

At build time, Nextra uses the fast-glob pattern {src/,}content to locate your content directory. It checks for content/ at the project root first, then falls back to src/content/. No manual configuration is needed — the directory is auto-detected. 
# Both of these are discovered automatically:
content/          ← root-level content directory
src/content/      ← src-nested content directory
Nextra then scans the discovered directory and collects every file with a .md or .mdx extension, along with any _meta.js configuration files.

​
Supported File Extensions

ExtensionDescription
.mdxMDX files — Markdown with embedded JSX components
.mdPlain Markdown files — processed the same way as MDX
Both extensions are treated identically in terms of routing and front matter parsing.

​
URL Route Mapping

Files inside content/ map directly to URL routes. The content/ directory itself is stripped from the path, and the file extension is removed:
File pathURL route
content/index.mdx/
content/about.mdx/about
content/docs/intro.mdx/docs/intro
content/docs/advanced/config.md/docs/advanced/config
content/docs/index.mdx/docs
An index.mdx file inside a subdirectory maps to the directory root. For example, content/docs/index.mdx is served at /docs.

​
Setting Up the content/ Directory

1
Create your first MDX page
2
Add an index.mdx file inside your content/ directory:
3
# Welcome to Nextra

Hello, world!
4
You can keep the content/ directory at the root of your project or inside a src/ directory. Nextra detects both automatically.
5
Set contentDirBasePath (optional)
6
If you want your content served from a sub-path instead of /, set the contentDirBasePath option in next.config.mjs:
7
import nextra from 'nextra'

const withNextra = nextra({
  contentDirBasePath: '/docs' // Or even nested, e.g. `/docs/advanced`
})

export default withNextra({})
8
Add the catch-all route file
9
Place a [[...mdxPath]]/page.jsx file inside your app/ directory. This single catch-all route acts as the gateway to your content/ directory and delegates rendering to Nextra:
10
export { generateStaticParams, default } from 'nextra/pages'
11
After this step, your project structure should look like:
12
your-project/
├── app/
│   ├── layout.jsx
│   └── [[...mdxPath]]/
│       └── page.jsx   ← catch-all route
├── content/
│   └── index.mdx      ← your first page
├── next.config.mjs
└── package.json
13
If you set contentDirBasePath in next.config.mjs, place [[...mdxPath]]/page.jsx inside the matching subdirectory. For example, contentDirBasePath: '/docs' → app/docs/[[...mdxPath]]/page.jsx.
14
You’re ready to go!
15
Start your development server. Nextra’s content/ directory has several advantages over third-party content-watching solutions:
16
  • No extra dependencies like concurrently or ws are required.
  • You do not need to restart the dev server when content files change.
  • Hot reloading works out of the box.
  • import statements inside MDX files work, and static images via next/image are automatically optimized.

    • ​
    Using src/content/

    If you prefer to keep application code under a src/ folder, move the content/ directory there: 
    your-project/
├── src/
│   ├── app/
│   │   ├── layout.jsx
│   │   └── [[...mdxPath]]/
│   │       └── page.jsx
│   └── content/          ← content lives here
│       └── index.mdx
├── next.config.mjs
└── package.json
    Nextra detects src/content/ using the same glob pattern and applies identical route mapping rules. No configuration change is needed.

    ​
    Example Directory Tree

    A typical docs site using the content/ directory might look like this: 
    content/
├── _meta.js              ← top-level navigation config
├── index.mdx             → /
├── getting-started.mdx   → /getting-started
├── about.mdx             → /about
└── docs/
    ├── _meta.js          ← docs section navigation config
    ├── index.mdx         → /docs
    ├── intro.mdx         → /docs/intro
    └── advanced/
        ├── _meta.js
        └── config.mdx    → /docs/advanced/config
    Each directory can contain a _meta.js file to control the order and titles of items in the sidebar.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us