Docs Theme

Nextra Docs Theme is a theme that includes almost everything you need to build a modern documentation website. It includes:

a top navigation bar
a search bar
a pages sidebar
a table of contents (TOC)
and other built-in components

Tip

This website itself is built with the Nextra Docs Theme.

Start as a New Project

Install

To create a Nextra Docs site manually, you have to install Next.js, React, Nextra, and Nextra Docs Theme. In your project directory, run the following command to install the dependencies:


npm i next react react-dom nextra nextra-theme-docs


pnpm add next react react-dom nextra nextra-theme-docs


yarn add next react react-dom nextra nextra-theme-docs


bun add next react react-dom nextra nextra-theme-docs

Note

If you already have Next.js installed in your project, you only need to install nextra and nextra-theme-docs as the add-ons.

Add the following scripts to your package.json:

package.json


{
  "scripts": {
    "dev": "next",
    "build": "next build",
    "start": "next start"
  }
}

Create a next.config.mjs file in your project’s root directory:

next.config.mjs


import nextra from 'nextra'
 
const withNextra = nextra({})
 
export default withNextra({})

Create an mdx-components.js file at the root of your project:

mdx-components.js


import { useMDXComponents as getMDXComponents } from 'nextra-theme-docs'
 
export function useMDXComponents(components) {
  return getMDXComponents(components)
}

Then create the root layout inside the app folder:

app/layout.jsx


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 metadata here
  // For more information on metadata API, 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>Nextra</b>}
    // ... Your additional navbar options
  />
)
const footer = <Footer>MIT {new Date().getFullYear()} © Nextra.</Footer>
 
export default async function RootLayout({ children }) {
  return (
    <html
      // Not required, but good for SEO
      lang="en"
      // Required to be set
      dir="ltr"
      // Suggested by `next-themes` package https://github.com/pacocoursey/next-themes#with-app
      suppressHydrationWarning
    >
      <Head
      // ... Your additional head options
      >
        {/* Your additional tags should be passed as `children` of `<Head>` element */}
      </Head>
      <body>
        <Layout
          banner={banner}
          navbar={navbar}
          pageMap={await getPageMap()}
          docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs"
          footer={footer}
          // ... Your additional layout options
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}

You are ready to start adding page.mdx files and organizing your docs with the App Router file conventions.

See the File Conventions for more details on organizing your documentation structure, and check out the Layout Component for configuring the docs site’s theme.