Skip to Content
🚧 This is WIP documentation for Nextra 4.0. Dima Machina is looking for a new job or consulting .

content Directory

The content directory is designed to:

  1. Migrate your existing Next.js pages router with minimal changes, you just need to rename your pages directory to content.
  2. Avoid having page filename convention, e.g. app/configuration/page.mdx -> content/configuration.mdx

Setup

Create your first MDX page as content/index.mdx:

content/index.mdx
# Welcome to Nextra Hello, world!
💡
Tip

You can keep content directory in root of your project, or in src directory.

Set contentDirBasePath option in next.config file (optional)

If you want to serve your content from a different path, you can set contentDirBasePath option:

next.config.mjs
import nextra from 'nextra' const withNextra = nextra({ contentDirBasePath: '/docs' // Or even nested e.g. `/docs/advanced` })

Add [[...mdxPath]]/page.jsx file

Place this file in app directory with the following content:

[[...mdxPath]]/page.jsx
import { generateStaticParamsFor, importPage } from 'nextra/pages' import { useMDXComponents } from '../../../../mdx-components' export const generateStaticParams = generateStaticParamsFor('mdxPath') export async function generateMetadata(props) { const params = await props.params const { metadata } = await importPage(params.mdxPath) return metadata } const Wrapper = useMDXComponents().wrapper export default async function Page(props) { const params = await props.params const result = await importPage(params.mdxPath) const { default: MDXContent, toc, metadata } = result return ( <Wrapper toc={toc} metadata={metadata}> <MDXContent {...props} params={params} /> </Wrapper> ) }

you should get the following structure:

    • layout.jsx
      • page.jsx
    • index.mdx
  • next.config.js
  • package.json
💡
Tip

Consider the single catch-all route [[...mdxPath]]/page.jsx as a gateway to your content directory.

If you set contentDirBasePath option in next.config file, you should put [[...mdxPath]]/page.jsx in the corresponding directory.

You are ready to go!

Note

Many existing solutions such as Refreshing the Next.js App Router When Your Markdown Content Changes  rely on extra dependencies like concurrently and ws. These approaches include Dan Abramov workaround with <AutoRefresh> component and dev web socket server.

Nextra’s content directory delivers a streamlined solution right out of the box:

  • you don’t need to install unnecessary dependencies
  • you don’t need to restart your server on changes in content directory
  • hot reloading works out of the box
  • you can use import statements in MDX files and static images works as well

Checkout Nextra’s docs website  and i18n website example .

Last updated on