Skip to Content
🎉 Nextra 4.0 已发布。Dima Machina 正在 寻找新的工作或咨询机会 。
Documentation文档主题内置组件布局

Layout 组件

主题通过 <Layout> 组件进行配置。你应该将配置选项作为 Layout 的 props 传递，例如：

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

详细的每个选项信息如下。

文档仓库

设置文档的仓库 URL。它用于生成”编辑此页”链接、“反馈”链接和未找到页面上的”报告损坏链接”.

OptionTypeDefault ValueDescription
docsRepositoryBasestring'https://github.com/shuding/nextra'URL of the documentation repository.

指定路径

如果文档在 monorepo、子文件夹或仓库的不同分支中，你可以简单地将 docsRepositoryBase 设置为文档的 app/ (App Router) 文件夹的根路径。例如：

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

然后 Nextra 将自动为所有页面生成正确的文件路径。

深色模式和主题

自定义网站的主题行为。

OptionTypeDefault ValueDescription
darkModebooleantrueShow or hide the dark mode select button.
nextThemesobject{ attribute: 'class', defaultTheme: 'system', disableTransitionOnChange: true, storageKey: 'theme' }Configuration for the next-themes  package.

MDX 组件 [!TODO]

提供自定义 MDX 组件  来渲染内容。例如，你可以使用自定义 pre 组件来渲染代码块。

OptionTypeDefault ValueDescription
componentsRecord<string, React.FC>Custom MDX components.

编辑链接

在页面上显示一个”编辑此页”的链接，指向 GitHub（或其他平台）上的文件 URL。

OptionTypeDefault ValueDescription
editLinkstring | ReactElement | null'Edit this page'Content of the edit link.
💡
Tip

要禁用它，你可以将 editLink 设置为 null。

反馈链接

内置的反馈链接为用户提供了提交文档反馈的途径。默认情况下，它是一个指向文档仓库问题创建表单的链接，预填充了当前网站标题： 示例 .

OptionTypeDefault ValueDescription
feedback.contentstring | ReactElement | null'Question? Give us feedback'Content of the feedback link.
feedback.labelsstring'feedback'Labels that can be added to the new created issue.
💡
Tip

要禁用它，你可以将 feedback.content 设置为 null.

国际化

用于配置 i18n 文档网站 的语言下拉菜单选项。

OptionTypeDefault ValueDescription
i18n[number].localestring来自 next.config 文件中 i18n.locales 字段的语言区域。
i18n[number].namestring下拉菜单中的语言名称。

最后更新日期

显示页面的最后更新日期。这对于显示内容的新鲜度很有用。

OptionTypeDefault ValueDescription
lastUpdatedReactElement | null<LastUpdated />用于渲染最后更新信息的组件。

Toggle Visibility

You can toggle visibility of the 最后更新日期 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
    }
  }
}

导航

在内容底部显示上一页和下一页链接。这对于在页面之间导航很有用。

OptionTypeDefault ValueDescription
navigationboolean | objecttrue启用或禁用导航链接。
navigation.prevboolean启用或禁用上一页链接。
navigation.nextboolean启用或禁用下一页链接。

导航

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]

侧边栏

OptionTypeDefault ValueDescription
sidebar.autoCollapseboolean如果为 true，自动折叠 defaultMenuCollapseLevel 以上的非活动文件夹。
sidebar.defaultMenuCollapseLevelnumber2指定左侧菜单默认折叠的文件夹级别。
sidebar.toggleButtonbooleantrue隐藏/显示侧边栏切换按钮。

菜单折叠级别

默认情况下，侧边栏菜单在级别 2 折叠。你可以通过将 sidebar.defaultMenuCollapseLevel 设置为不同的数字来改变它。例如，当设置为 1 时，每个文件夹默认都会折叠，当设置为 Infinity 时，所有嵌套文件夹默认都会展开。

如果将 sidebar.autoCollapse 设置为 true，则所有不包含活动/焦点路由的文件夹将自动折叠到 sidebar.defaultMenuCollapseLevel 设置的级别。例如，如果 defaultMenuCollapseLevel 是 2，则顶级文件夹将不会自动折叠。

自定义侧边栏内容

结合 分隔符 项，你可以使用 JSX 元素自定义侧边栏内容的渲染方式：

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

使用 Front Matter 自定义侧边栏

此外，你可以使用 front matter 中的 sidebarTitle 属性来自定义侧边栏标题：

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

侧边栏标题的优先级如下：

  1. _meta 文件中的非空标题。
  2. front matter 中的 sidebarTitle。
  3. front matter 中的 title。
  4. 从第一个 h1 Markdown 标题派生的标题（例如 # Dima Machina）。
  5. 如果以上都不可用，则回退到页面的文件名，根据 芝加哥格式手册  进行格式化。

主题切换

OptionTypeDefault ValueDescription
themeSwitch{ light: string; dark: string; system: string }{ light: 'Light', dark: 'Dark', system: 'System' }主题切换中的选项翻译。

你可以自定义选项名称以进行本地化或其他目的：

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

目录（TOC）侧边栏

在页面右侧显示目录。这对于在标题之间导航很有用。

OptionTypeDefault ValueDescription
toc.backToTopstring | ReactElement | null'Scroll to top'返回顶部按钮的文本。
toc.extraContentstring | ReactElement | null在 TOC 内容下方显示额外内容。
toc.floatbooleantrue使 TOC 浮动在内容旁边。
toc.titlestring | ReactElement | null'On This Page'TOC 侧边栏的标题。

浮动 TOC

启用后，TOC 将显示在页面右侧，并在滚动时保持固定。如果禁用，TOC 将直接显示在页面侧边栏中。

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
内置组件页脚