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 Nextra Docs Theme gives you a production-ready documentation site out of the box. It ships with a top navigation bar, a collapsible pages sidebar, full-text search, a floating table of contents, dark mode, and a rich set of built-in components — all driven by your MDX content files with zero configuration required.
This page covers a manual setup. If you prefer a one-command scaffold, the Nextra team also maintains a starter template you can deploy directly to Vercel.

​
What You Get

  • Top navigation bar with logo, links, and theme switcher
  • Collapsible sidebar generated automatically from your content directory
  • Full-text search powered by Nextra’s built-in search index
  • Floating table of contents for every page
  • Dark mode via next-themes
  • MDX with syntax highlighting, callouts, tabs, and more built-in components

​
Manual Setup

1
Install dependencies
2
Create a new directory for your project and install Next.js, React, Nextra, and Nextra Docs Theme:
3
npm
npm install next react react-dom nextra nextra-theme-docs
yarn
yarn add next react react-dom nextra nextra-theme-docs
pnpm
pnpm add next react react-dom nextra nextra-theme-docs
bun
bun add next react react-dom nextra nextra-theme-docs
4
If you already have a Next.js project, you only need to add nextra and nextra-theme-docs — Next.js, React, and React DOM are already present.
5
Configure the Nextra plugin
6
Create next.config.mjs at the root of your project and wrap your Next.js config with the nextra() plugin:
7
import nextra from 'nextra'

const withNextra = nextra({
  // Nextra-specific options go here.
  // For example, enable LaTeX rendering:
  // latex: true,
  //
  // Restrict the content directory base path:
  // contentDirBasePath: '/docs',
})

export default withNextra({
  // Regular Next.js options go here.
  reactStrictMode: true,
})
8
The nextra() call returns a withNextra wrapper. Pass your standard NextConfig object to withNextra(...) — Nextra merges its own webpack rules and page extensions automatically.
9
Create the root layout
10
Create app/layout.tsx (or app/layout.jsx). This is where you assemble the docs shell: the <Head>, the <Layout> container, a <Navbar>, and a <Footer>. The getPageMap() call reads your content directory at build time and feeds the sidebar.
11
import { Footer, Layout, Navbar } from 'nextra-theme-docs'
import { Banner, Head } from 'nextra/components'
import { getPageMap } from 'nextra/page-map'
import 'nextra-theme-docs/style.css'

export const metadata = {
  // Define your site-wide metadata here.
  // See: https://nextjs.org/docs/app/building-your-application/optimizing/metadata
}

const banner = (
  <Banner storageKey="some-key">Nextra 4.0 is released 🎉</Banner>
)

const navbar = (
  <Navbar
    logo={<b>My Site</b>}
    // chatLink="https://discord.gg/yourserver"
  />
)

const footer = (
  <Footer>MIT {new Date().getFullYear()} © My Company.</Footer>
)

export default async function RootLayout({ children }) {
  return (
    <html
      lang="en"
      dir="ltr"
      // Required by next-themes for flicker-free dark mode
      suppressHydrationWarning
    >
      <Head />
      <body>
        <Layout
          banner={banner}
          navbar={navbar}
          pageMap={await getPageMap()}
          docsRepositoryBase="https://github.com/your-org/your-repo/tree/main/docs"
          footer={footer}
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}
12
Pass dir="ltr" or dir="rtl" on the <html> element to control reading direction. The lang attribute improves SEO and accessibility.
13
Create the MDX components file
14
Nextra uses a mdx-components file to let you override or extend the default MDX element renderers. Create it at the project root:
15
import { useMDXComponents as getDocsMDXComponents } from 'nextra-theme-docs'

const docsComponents = getDocsMDXComponents()

export const useMDXComponents = (components) => ({
  ...docsComponents,
  ...components,
})
16
This merges the docs theme’s built-in component overrides (code blocks, callouts, headings, etc.) with any custom components you supply per-page.
17
Add your first content page
18
By default, Nextra looks for content in the content/ directory (or src/content/). Create your index page:
19
# Welcome to My Docs

This is the home page of your Nextra-powered documentation site.
Start editing this file or add new `.mdx` files alongside it —
the sidebar updates automatically.
20
Nextra maps every .md and .mdx file in content/ to a URL. A file at content/guide/installation.mdx becomes /guide/installation. You can control the sidebar title and order with _meta.js files in each directory.
21
Start the development server
22
npm
npm run dev
yarn
yarn dev
pnpm
pnpm dev
bun
bun dev
23
Open http://localhost:3000. You should see your docs site with the sidebar, navbar, and search bar ready to use.

​
Layout Props Reference

The <Layout> component from nextra-theme-docs accepts a rich set of props to customise every aspect of the docs shell.
PropTypeDefaultDescription
toc.titleReactNode'On This Page'Title above the TOC
toc.backToTopReactNode'Scroll to top'Back-to-top button label
toc.floatbooleantrueFloat the TOC beside the content
toc.extraContentReactNode—Extra content rendered below the TOC
PropTypeDefaultDescription
darkModebooleantrueShow the dark mode toggle
nextThemes.defaultThemestring'system'Initial theme ('light', 'dark', or 'system')
nextThemes.storageKeystring'theme'localStorage key for the selected theme
themeSwitch.darkstring'Dark'Label for the dark option
themeSwitch.lightstring'Light'Label for the light option
themeSwitch.systemstring'System'Label for the system option

​
Content Directory Structure

A typical Nextra docs project looks like this: 
my-docs/
├── app/
│   └── layout.tsx       # Root layout with <Layout>, <Navbar>, <Footer>
├── content/
│   ├── _meta.js         # Sidebar order & titles for this level
│   ├── index.mdx        # Rendered at /
│   ├── guide/
│   │   ├── _meta.js
│   │   ├── installation.mdx
│   │   └── configuration.mdx
│   └── api/
│       └── reference.mdx
├── mdx-components.js    # MDX component overrides
├── next.config.mjs      # Nextra plugin config
└── package.json
Use _meta.js files to control the order and display names of pages in the sidebar without renaming files. Export a plain object whose keys are filenames (without extension) and values are display strings or config objects.

​
Next Steps

Blog Theme

Set up a blog with post listings, tags, RSS, and reading-time estimates.

Custom Theme

Build your own layout component and consume the page map directly.

File Conventions

Learn about _meta.js, mdx-components, and the content directory.

Built-in Components

Explore Callout, Tabs, Steps, Cards, and other ready-made MDX components.

Build docs developers (and LLMs) love

Get started for freeTalk to us