Skip to Content
Nextra 4.0 is released. Read more
DocumentationDocs ThemeBuilt-In ComponentsLayout

Layout

The theme is configured with the <Layout> component. You should pass your config options as Layout’s props, for example:

app/layout.jsx
import { Layout } from 'nextra-theme-docs'
 
export default function MyLayout({ children, ...props }) {
  return (
    <html lang="en">
      <body>
        <Layout
          logo={<b>Project</b>}
          docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs"
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}

Detailed information for each option is listed below.

Docs Repository

Set the repository URL of the documentation. It’s used to generate the “Edit this page” link, the “Feedback” link and “Report of broken link” on not found page .

OptionTypeDescription
docsRepositoryBasestringURL of the documentation repository.
Default: "https://github.com/shuding/nextra"

Specify a Path

If the documentation is inside a monorepo, a subfolder, or a different branch of the repository, you can simply set the docsRepositoryBase to the root path of the app/ (App Router) folder of your docs. For example:

app/layout.jsx
<Layout docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs">
  {children}
</Layout>

Then Nextra will automatically generate the correct file path for all pages.

Dark Mode and Themes

Customize the theme behavior of the website.

OptionTypeDescription
darkModebooleanShow or hide the dark mode select button. Default: "true"
nextThemesobjectConfiguration for the next-themes  package.
Default: { attribute: 'class', defaultTheme: 'system', disableTransitionOnChange: true, storageKey: 'theme' }

MDX Components [!TODO]

Provide custom MDX components  to render the content. For example, you can use a custom pre component to render code blocks.

OptionTypeDescription
componentsRecord<string, React.FC>Custom MDX components

Edit Link

Show an “Edit this page” link on the page that points to the file URL on GitHub (or other places).

OptionTypeDescription
editLinkstring | ReactElement | nullContent of the edit link. Default: "Edit this page"
💡
Tip

To disable it, you can set editLink to null.

Feedback Link

The built-in feedback link provides a way for users to submit feedback about the documentation. By default, it’s a link that points to the issue creation form of the docs repository, with the current website title prefilled: example .

OptionTypeDescription
feedback.contentstring | ReactElement | nullContent of the feedback link.
Default: "Question? Give us feedback"
feedback.labelsstringLabels that can be added to the new created issue.
Default: "feedback"
💡
Tip

To disable it, you can set feedback.content to null.

I18n

Options to configure the language dropdown for the i18n docs website.

OptionTypeDescription
i18n[number].localestringLocale from i18n.locales field in next.config file
i18n[number].namestringLocale name in dropdown

Last Updated Date

Show the last updated date of a page. It’s useful for showing the freshness of the content.

OptionTypeDescription
lastUpdatedReactElement | nullComponent to render the last updated info.
Default: <LastUpdated />

Toggle Visibility

You can toggle visibility of the last update date on the specific pages by setting theme.timestamp property in the _meta.js file:

_meta.js
export default {
  'my-page': {
    theme: {
      timestamp: false // Hide timestamp on this page
    }
  }
}

Navigation

Show previous and next page links on the bottom of the content. It’s useful for navigating between pages.

OptionTypeDescription
navigationboolean | objectEnable or disable navigation link. Default: true
navigation.prevbooleanEnable or disable the previous page link
navigation.nextbooleanEnable or disable the next page link
Navigation
app/layout.jsx
<Layout
  navigation={{
    prev: true,
    next: true
  }}
>
  {children}
</Layout>

The above is also equivalent to navigation: true.

Toggle Visibility

You can toggle visibility of the navigation on the specific pages by setting theme.pagination property in the _meta.js file:

_meta.js
export default {
  'my-page': {
    theme: {
      pagination: false // Hide pagination on this page
    }
  }
}

Page Map [!TODO]

Search [!TODO]

Sidebar

OptionTypeDescription
sidebar.autoCollapsebooleanIf true, automatically collapse inactive folders above defaultMenuCollapseLevel
sidebar.defaultMenuCollapseLevelnumberSpecifies the folder level at which the menu on the left is collapsed by default. Default: 2
sidebar.toggleButtonbooleanHide/show sidebar toggle button. Default: true

Menu Collapse Level

By default, the sidebar menu is collapsed at level 2. You can change it by setting sidebar.defaultMenuCollapseLevel to a different number. For example, when set to 1, every folder will be collapsed by default and when set to Infinity, all nested folders will be expanded by default.

If sidebar.autoCollapse is set to true, then all folders that do not contain an active/focused route will automatically collapse up to the level set by sidebar.defaultMenuCollapseLevel. e.g. if defaultMenuCollapseLevel is 2, then top-level folders will not auto-collapse.

Customize Sidebar Content

Together with the Separators item, you can customize how the sidebar content is rendered by using JSX elements:

_meta.jsx
export default {
  index: 'Intro',
  '--': {
    type: 'separator',
    title: (
      <div className="flex items-center gap-2">
        <MyLogo />
        {children}
      </div>
    )
  },
  frameworks: 'JS Frameworks & Libs',
  about: 'About'
}
Customized Sidebar

Toggle Visibility

You can toggle visibility of the <Sidebar> on the specific pages by setting theme.sidebar property in the _meta.js file:

_meta.js
export default {
  'my-page': {
    theme: {
      sidebar: false // Hide sidebar on this page
    }
  }
}

Customize Sidebar with Front Matter

In addition, you can customize the sidebar title using the sidebarTitle property in your front matter:

pages/getting-started.mdx
---
sidebarTitle: Getting Started 🚀
---

The priority of the sidebar title is as follows:

  1. title property from _meta.js file
  2. Front matter sidebarTitle
  3. Front matter title
  4. Filename of the page formatted with Title 

Theme Switch

OptionTypeDescription
themeSwitch{ light: string; dark: string; system: string }Translation of options in the theme switch.
Default: { light: 'Light', dark: 'Dark', system: 'System' }

You are able to customize the option names for localization or other purposes:

app/layout.jsx
<Layout
  themeSwitch={{
    dark: 'Темный',
    light: 'Светлый',
    system: 'Системный'
  }}
>
  {children}
</Layout>

Table of Contents (TOC) Sidebar

Show a table of contents on the right side of the page. It’s useful for navigating between headings.

OptionTypeDescription
toc.backToTopstring | ReactElement | nullText of back to top button. Default: "Scroll to top"
toc.extraContentstring | ReactElement | nullDisplay extra content below the TOC content
toc.floatbooleanFloat the TOC next to the content. Default: true
toc.titlestring | ReactElement | nullTitle of the TOC sidebar. Default: "On This Page"

Floating TOC

When enabled, the TOC will be displayed on the right side of the page, and it will be sticky when scrolling. If it’s disabled, the TOC will be displayed directly on the page sidebar.

Toggle Visibility

You can toggle visibility of the <TOC> on the specific pages by setting theme.toc property in the _meta.js file:

_meta.js
export default {
  'my-page': {
    theme: {
      toc: false // Hide toc on this page
    }
  }
}
Last updated on
FooterNavbar