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.

This website itself is built with the Nextra docs theme.

Quick Start from Template

Deploy to Vercel

You can start by creating your own Nextra site and deploying to Vercel by clicking the link:

Vercel will fork the Nextra docs template and deploy the site for you. Once done, every commit in the repository will be deployed automatically.

Fork the Template

You can also manually fork the template repository .

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 in package.json:

package.json

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

💡

Tip

You can use Turbopack by appending --turbopack flag in dev command

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 the following next.config.mjs file in your project’s root directory:

next.config.mjs

import nextra from 'nextra'
 
const withNextra = nextra({
  // ... Other Nextra config options
})
 
// If you have other Next.js configurations, you can pass them as the parameter:
export default withNextra({
  // ... Other Next.js config options
})

With the above configuration, Nextra can handle Markdown files in your Next.js project, with the specified theme. Other Nextra configurations can be found in Guide.

Add `mdx-components.js` in root directory

mdx-components.js

import { useMDXComponents as getDocsMDXComponents } from 'nextra-theme-docs'
 
const docsComponents = getDocsMDXComponents()
 
export function useMDXComponents(components) {
  return {
    ...docsComponents,
    ...components
  }
}

💡

Tip

You can use .jsx, .ts and .tsx extensions for your mdx-components file as well.

Create Root Layout

Lastly, create the root layout of your application in app folder. This 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 = {
  // ... Your metadata API
  // 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>
  )
}

Ready to Go!

Now, you can create your first MDX page as content/index.mdx:

content/index.mdx

# Welcome to Nextra
 
Hello, world!

And 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: