Nextra Docs Theme: Full-Featured Documentation Layout

The Nextra Docs Theme (nextra-theme-docs) is a full-featured documentation layout that wraps your Next.js App Router application with a polished, accessible shell — including a top navigation bar, collapsible sidebar, floating table of contents, full-text search via Pagefind, dark mode, and edit-on-GitHub links. Configure everything through the <Layout> component’s props in your root app/layout.jsx.

What’s Included

The docs theme bundles a rich set of UI features out of the box:

Top Navigation Bar

Logo, project link, chat link, and custom menu items rendered in a sticky navbar.

Full-Text Search

Pagefind-powered static search via the built-in <Search /> component.

Collapsible Sidebar

Auto-collapsing page tree with configurable default collapse level and toggle button.

Floating TOC on the right side of the page, sticky on scroll, with a back-to-top link.

Dark Mode Toggle

Seamless light/dark/system switching powered by next-themes.

Edit on GitHub

Per-page “Edit this page” link derived from docsRepositoryBase.

Feedback Link

Inline feedback button that opens a pre-filled GitHub issue.

Previous / Next Pagination

Bottom-of-page navigation links to adjacent pages in the sidebar tree.

Last Updated Timestamp

Displays the most recent git commit date for each page.

i18n Locale Switcher

Dropdown for multi-language sites configured via Next.js i18n.

Installation

Install the package

npm

npm install nextra nextra-theme-docs

pnpm

pnpm add nextra nextra-theme-docs

yarn

yarn add nextra nextra-theme-docs

Configure Nextra in next.config.js

import nextra from 'nextra'

const withNextra = nextra({
  defaultShowCopyCode: true
})

export default withNextra({
  reactStrictMode: true
})

Create the root layout

Create app/layout.jsx and wrap your application with <Layout> from nextra-theme-docs. Pass pageMap from nextra/page-map so the sidebar and navigation are generated automatically:

import { Layout, Navbar, Footer } from 'nextra-theme-docs'
import { getPageMap } from 'nextra/page-map'
import 'nextra-theme-docs/style.css'

export default async function RootLayout({ children }) {
  const pageMap = await getPageMap()
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <Layout
          pageMap={pageMap}
          docsRepositoryBase="https://github.com/your-org/your-repo/tree/main/docs"
          navbar={<Navbar logo={<strong>My Docs</strong>} />}
          footer={<Footer>MIT {new Date().getFullYear()} © Your Name.</Footer>}
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}

Add MDX components

Create mdx-components.js at the project root to enable MDX rendering:

export { useMDXComponents } from 'nextra-theme-docs'

Layout Component

The <Layout> component is the central configuration point for the docs theme. Every visual and behavioral option is controlled through its props.

import { Layout } from 'nextra-theme-docs'

Props Reference

`pageMap`

pageMap

PageMapItem[]

required

The page map list — the result of calling getPageMap('/') from nextra/page-map. This drives the sidebar, navigation links, and breadcrumbs. You must pass this prop for the sidebar to render correctly.

import { getPageMap } from 'nextra/page-map'

// Inside an async Server Component:
const pageMap = await getPageMap()

<Layout pageMap={pageMap}>
  {children}
</Layout>

`children`

children

ReactNode

required

The page content rendered inside the layout. This is always the {children} passed by Next.js to the root layout component.

A rendered <Navbar> component. Import Navbar from nextra-theme-docs, configure its props, and pass the element here. If omitted, no navbar is rendered.

import { Navbar } from 'nextra-theme-docs'

<Layout navbar={<Navbar logo={<strong>My Docs</strong>} projectLink="https://github.com/my-org/my-repo" />}>
  {children}
</Layout>

footer

ReactNode

A rendered <Footer> component. Import Footer from nextra-theme-docs and pass the element here. Children of <Footer> render as the footer content (e.g. copyright text).

import { Footer } from 'nextra-theme-docs'

<Layout footer={<Footer>MIT {new Date().getFullYear()} © Nextra.</Footer>}>
  {children}
</Layout>

banner

ReactNode

A rendered <Banner> component displayed above the navbar. Import Banner from nextra/components. Useful for announcing new releases or important notices.

import { Banner } from 'nextra/components'

<Layout banner={<Banner storageKey="v4-release">🎉 Version 4.0 is out! <a href="/blog/v4">Read more →</a></Banner>}>
  {children}
</Layout>

`docsRepositoryBase`

docsRepositoryBase

string

default:"https://github.com/shuding/nextra"

The base URL of the documentation repository. Must start with https://. Used to construct the “Edit this page” link and the feedback issue link for each page.For monorepos or subdirectory layouts, point this at the app/ folder directly:

<Layout docsRepositoryBase="https://github.com/your-org/your-repo/tree/main/docs">
  {children}
</Layout>

`editLink`

editLink

ReactNode

default:"'Edit this page'"

The content rendered inside the edit link at the bottom of each page. Set to null to disable the edit link entirely.

// Custom text
<Layout editLink="Improve this page on GitHub">

// Disable
<Layout editLink={null}>

`feedback`

feedback

object

Configuration for the per-page feedback link. By default, it links to a pre-filled GitHub issue form.

Field	Type	Default	Description
`content`	`ReactNode`	`'Question? Give us feedback'`	Label text for the feedback link. Set to `null` to hide it.
`labels`	`string`	`'feedback'`	GitHub issue labels applied to newly created feedback issues.
`link`	`string`	Auto-generated	Custom URL for the feedback link. Overrides the default GitHub issue link.

<Layout
  feedback={{
    content: 'Was this page helpful?',
    labels: 'docs-feedback',
  }}
>
  {children}
</Layout>

`search`

ReactNode

default:"<Search />"

The search component rendered in the navbar. Defaults to the Pagefind-powered <Search /> from nextra/components. Pass a custom component or null to disable search.

import { Search } from 'nextra/components'

// Default (equivalent)
<Layout search={<Search />}>

// Disable search
<Layout search={null}>

`darkMode`

darkMode

boolean

default:"true"

Show or hide the dark mode toggle button. When set to false, the theme selector is removed from the UI but the nextThemes configuration still applies.

`nextThemes`

nextThemes

object

Configuration passed directly to the next-themes ThemeProvider. All fields are optional.

Field	Type	Default	Description
`attribute`	`'class' \|` data-$“	`'class'`	HTML attribute modified to apply the theme.
`defaultTheme`	`string`	`'system'`	Default theme name.
`disableTransitionOnChange`	`boolean`	`true`	Disable CSS transitions when switching themes.
`forcedTheme`	`string`	—	Forces a specific theme, overriding user preference.
`storageKey`	`string`	`'theme'`	`localStorage` key used to persist the user’s theme choice.

<Layout
  darkMode={true}
  nextThemes={{
    defaultTheme: 'dark',
    storageKey: 'my-docs-theme'
  }}
>
  {children}
</Layout>

Show or hide the previous/next page navigation links at the bottom of each page. Pass false to hide both, true to show both, or an object for granular control.

// Show both (default)
<Layout navigation={true}>

// Hide both
<Layout navigation={false}>

// Show only "next"
<Layout navigation={{ prev: false, next: true }}>

sidebar

object

Controls the behavior and appearance of the left sidebar. All sub-fields are optional.

Field	Type	Default	Description
`autoCollapse`	`boolean`	—	When `true`, automatically collapse inactive folders above `defaultMenuCollapseLevel`.
`defaultMenuCollapseLevel`	`number` (int ≥ 1)	`2`	Folder depth at which the sidebar is collapsed by default. Set to `1` to collapse all top-level folders, `Infinity` to expand everything.
`defaultOpen`	`boolean`	`true`	Whether the sidebar is open by default.
`toggleButton`	`boolean`	`true`	Show or hide the sidebar toggle button.

<Layout
  sidebar={{
    autoCollapse: true,
    defaultMenuCollapseLevel: 1,
    defaultOpen: true,
    toggleButton: true
  }}
>
  {children}
</Layout>

Set sidebar.autoCollapse: true together with a low defaultMenuCollapseLevel to keep deep documentation trees tidy — only the active section stays expanded.

`toc`

toc

object

Controls the Table of Contents displayed on the right side of each page.

Field	Type	Default	Description
`backToTop`	`ReactNode`	`'Scroll to top'`	Text for the back-to-top button at the bottom of the TOC.
`extraContent`	`ReactNode`	—	Additional content rendered below the TOC items.
`float`	`boolean`	`true`	When `true`, the TOC floats next to the content (sticky on scroll). When `false`, it appears inline in the sidebar.
`title`	`ReactNode`	`'On This Page'`	Title heading above the TOC item list.

<Layout
  toc={{
    float: true,
    title: 'Contents',
    backToTop: '↑ Back to top',
    extraContent: <NewsletterSignup />
  }}
>
  {children}
</Layout>

`themeSwitch`

themeSwitch

object

Translatable labels for the theme switcher options. Useful for i18n sites.

Field	Type	Default
`dark`	`string`	`'Dark'`
`light`	`string`	`'Light'`
`system`	`string`	`'System'`

// Russian locale example
<Layout
  themeSwitch={{
    dark: 'Тёмная',
    light: 'Светлая',
    system: 'Системная'
  }}
>
  {children}
</Layout>

`i18n`

i18n

{ locale: string, name: string }[]

default:"[]"

Options for the language dropdown rendered in the navbar. Each entry maps a Next.js locale code (from i18n.locales in next.config.js) to a human-readable display name.

<Layout
  i18n={[
    { locale: 'en', name: 'English' },
    { locale: 'zh-CN', name: '中文' },
    { locale: 'de', name: 'Deutsch' }
  ]}
>
  {children}
</Layout>

`lastUpdated`

lastUpdated

ReactElement

default:"<LastUpdated />"

Component rendered to show the last-updated date at the bottom of each page. Must be a <LastUpdated /> element — passing a plain string or <div> will throw a validation error. Use the locale prop to localize the date format.

import { Layout, LastUpdated } from 'nextra-theme-docs'

<Layout lastUpdated={<LastUpdated locale="de-DE" />}>
  {children}
</Layout>

`copyPageButton`

copyPageButton

boolean

default:"true"

Show or hide the “Copy page content” button. When enabled, users can copy the entire Markdown content of the current page to the clipboard.

The <Navbar> component renders the sticky top navigation bar with a logo, project links, and optional custom items.

import { Navbar } from 'nextra-theme-docs'

logo

ReactNode

required

The logo element displayed on the left side of the navbar.

logoLink

string | boolean

default:"true"

Controls whether the logo is wrapped in a link. Pass true (default) to link to /, a string URL to link elsewhere, or false to render the logo without a link.

projectLink

string

URL for the project icon button (top-right). Defaults to the Nextra GitHub repository.

projectIcon

ReactNode

Custom icon for the project link button. Defaults to a GitHub icon.

chatLink

string

URL for a secondary icon button — typically a Discord, Slack, or social link.

chatIcon

ReactNode

Custom icon for the chat link button. Defaults to a Discord icon.

children

ReactNode

Extra content rendered after the last icon in the navbar — typically used for a <Search /> component or locale switcher.

align

'left' | 'right'

default:"'right'"

Aligns the navigation icons to the specified side of the navbar.

className

string

Additional CSS class name applied to the <nav> element.

Custom Logo
GitLab Project Link
Chat / Social Link

<Navbar
  logo={
    <>
      <svg width="24" height="24" viewBox="0 0 24 24">
        <path fill="currentColor" d="M12 2L2 7l10 5 10-5-10-5z" />
      </svg>
      <span style={{ marginLeft: '0.4em', fontWeight: 800 }}>My Docs</span>
    </>
  }
/>

<Navbar
  projectLink="https://gitlab.com/my-org/my-project"
  projectIcon={
    <svg width="24" height="24" fill="currentColor" viewBox="0 0 256 256">
      <path d="m231.9 169.8l-94.8 65.6a15.7 15.7 0 0 1-18.2 0l-94.8-65.6..." />
    </svg>
  }
/>

The <Footer> component renders a simple footer area. Pass children to provide copyright text, links, or other content.

import { Footer } from 'nextra-theme-docs'

import { Footer, Layout } from 'nextra-theme-docs'

export default async function RootLayout({ children }) {
  return (
    <Layout
      footer={
        <Footer>
          MIT {new Date().getFullYear()} ©{' '}
          <a href="https://nextra.site" target="_blank">
            Nextra
          </a>
          .
        </Footer>
      }
    >
      {children}
    </Layout>
  )
}

All Named Exports

The following are all named exports available from nextra-theme-docs:

Components

Export	Description
`Layout`	Root layout component — wraps the entire page tree
`Navbar`	Top navigation bar
`Footer`	Page footer
`NotFoundPage`	Pre-built 404 page component
`ThemeSwitch`	Standalone dark/light/system mode selector
`LocaleSwitch`	Locale dropdown for i18n sites
`LastUpdated`	Displays the last git-commit timestamp for a page

Hooks and Utilities

Export	Description
`useThemeConfig`	React hook — access the resolved theme configuration
`useConfig`	React hook — access the current page config
`useMenu`	React hook — read the current sidebar open/close state
`setMenu`	Setter function — programmatically open or close the sidebar
`useMDXComponents`	MDX component map hook — use in `mdx-components.js`
`useTheme`	Re-exported from `next-themes` — access the active theme
`Link`	Internal link component with active-state styling

Usage example

export { useMDXComponents } from 'nextra-theme-docs'

import {
  useThemeConfig,
  useConfig,
  useMenu,
  setMenu,
  ThemeSwitch,
  LocaleSwitch,
  LastUpdated
} from 'nextra-theme-docs'

// Read the merged theme config
const config = useThemeConfig()

// Toggle the sidebar programmatically
setMenu(true)

// Render individual components standalone
<ThemeSwitch />
<LocaleSwitch />
<LastUpdated locale="en-US" />

Complete Layout Example

The following shows a real-world root layout combining the most common options:

import { Banner, Search } from 'nextra/components'
import { getPageMap } from 'nextra/page-map'
import {
  Footer,
  LastUpdated,
  Layout,
  LocaleSwitch,
  Navbar
} from 'nextra-theme-docs'
import 'nextra-theme-docs/style.css'

export default async function RootLayout({ children }) {
  const pageMap = await getPageMap()

  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <Layout
          pageMap={pageMap}
          docsRepositoryBase="https://github.com/my-org/my-repo/tree/main/docs"
          banner={
            <Banner storageKey="v2-release">
              🎉 Version 2.0 released —{' '}
              <a href="/blog/v2">see what's new</a>
            </Banner>
          }
          navbar={
            <Navbar
              logo={<strong>My Project</strong>}
              projectLink="https://github.com/my-org/my-repo"
            >
              <Search />
              <LocaleSwitch />
            </Navbar>
          }
          footer={
            <Footer>
              MIT {new Date().getFullYear()} © My Organization.
            </Footer>
          }
          sidebar={{ autoCollapse: true, defaultMenuCollapseLevel: 1 }}
          toc={{ title: 'On This Page', float: true }}
          editLink="Edit this page on GitHub"
          lastUpdated={<LastUpdated locale="en-US" />}
          navigation={{ prev: true, next: true }}
          darkMode={true}
          i18n={[
            { locale: 'en', name: 'English' },
            { locale: 'fr', name: 'Français' }
          ]}
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}

pageMap must be awaited inside an async Server Component. The getPageMap() function reads from the filesystem at build time, so it cannot be called inside a Client Component.

Getting Started

File Conventions

Writing Content

Built-In Components

Themes

Advanced

Documentation Index

​What’s Included

Top Navigation Bar

Full-Text Search

Collapsible Sidebar

Table of Contents

Dark Mode Toggle

Edit on GitHub

Feedback Link

Previous / Next Pagination

Last Updated Timestamp

i18n Locale Switcher

​Installation

​Layout Component

​Props Reference

​pageMap

​children

​navbar

​footer

​banner

​docsRepositoryBase

​editLink

​feedback

​search

​darkMode

​nextThemes

​navigation

​sidebar

​toc

​themeSwitch

​i18n

​lastUpdated

​copyPageButton

​Navbar Component

​Navbar Props

​Navbar Examples

​Footer Component

​All Named Exports

​Usage example

​Complete Layout Example

Build docs developers (and LLMs) love

What’s Included

Installation

Layout Component

Props Reference

`pageMap`

`children`

`navbar`

`footer`

`banner`

`docsRepositoryBase`

`editLink`

`feedback`

`search`

`darkMode`

`nextThemes`

`navigation`

`sidebar`

`toc`

`themeSwitch`

`i18n`

`lastUpdated`

`copyPageButton`

Navbar Component

Navbar Props

Navbar Examples

Footer Component

All Named Exports

Usage example

Complete Layout Example