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"
},

💡

Tip

You can enable Turbopack in development by appending the --turbopack flag to the dev command:

package.json


- "dev": "next",
+ "dev": "next --turbopack",

You can start the server in development mode with the following command according to your package manager:


npm run dev


pnpm run dev


yarn dev


bun run dev

or in production mode:


npm run build
npm run start


pnpm run build
pnpm run start


yarn build
yarn run start


bun run build
bun run start

Note

If you’re not familiar with Next.js, note that development mode is significantly slower since Next.js compiles every page you navigate to.

Add Next.js config

Create a next.config.mjs file in your project’s root directory with the following content:

next.config.mjs


import nextra from 'nextra'
 
const withNextra = nextra({
  // ... Other Nextra config options
})
 
// You can include other Next.js configuration options here, in addition to Nextra settings:
export default withNextra({
  // ... Other Next.js config options
})

With this configuration, Nextra will handle Markdown files in your Next.js project. For more Nextra configuration options, check out the Guide.

Add `mdx-components` file

Create the Root Layout

Next, create the root layout of your application inside the app folder. This layout will be used to configure the Nextra Docs Theme:

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>
  )
}

Render MDX files

There are two ways to render MDX files using file-based routing, add your MDX files via page files or content directory convention.

Run the project

Run the dev command specified in package.json to start developing the project! 🎉


npm run dev


pnpm run dev


yarn dev


bun run dev

Next, check out the next section to learn about organizing the documentation structure and configuring the website theme.