主题配置
主题是使用 theme.config.jsx 文件配置的。它应该导出一个包含你的配置的对象,例如
export default {
project: {
link: 'https://github.com/shuding/nextra'
},
logo: <b>Project</b>
}
下面列出了每个选项的详细信息。
全局
文档仓库
设置文档的仓库 URL。它用于生成“编辑此页面”链接和“反馈”链接。
选项 | 类型 | 描述 |
---|---|---|
docsRepositoryBase | 字符串 | 文档仓库的 URL |
指定路径
如果文档位于单体仓库、子文件夹或仓库的不同分支中,你可以简单地将 docsRepositoryBase
设置为文档 pages/
文件夹的根路径。例如
export default {
docsRepositoryBase: 'https://github.com/shuding/nextra/tree/main/docs'
}
然后 Nextra 将自动为所有页面生成正确的文件路径。
头部标签
配置网站的 <head>
标签。你可以添加元标签、标题、favicon 等。
选项 | 类型 | 描述 |
---|---|---|
head | React.ReactNode | React.FC | 渲染 <head> 内容的组件 |
静态头部标签
如果你只有静态头部标签,可以很容易地将它们直接放在 head
中。例如
export default {
head: (
<>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta property="og:title" content="Nextra" />
<meta property="og:description" content="The next site builder" />
</>
)
}
基于页面的动态标签
你也可以使用一个函数组件作为 head
,根据当前页面的前置 matter 动态生成头部标签。例如
import { useRouter } from 'next/router'
import { useConfig } from 'nextra-theme-docs'
export default {
head() {
const { asPath, defaultLocale, locale } = useRouter()
const { frontMatter } = useConfig()
const url =
'https://my-app.com' +
(defaultLocale === locale ? asPath : `/${locale}${asPath}`)
return (
<>
<meta property="og:url" content={url} />
<meta property="og:title" content={frontMatter.title || 'Nextra'} />
<meta
property="og:description"
content={frontMatter.description || 'The next site builder'}
/>
</>
)
}
}
你可以参考 useConfig
API 部分,了解有关 useConfig
钩子和 frontMatter
对象的更多信息。
暗黑模式和主题
自定义网站的主题行为。
选项 | 类型 | 描述 |
---|---|---|
darkMode | 布尔值 | 显示或隐藏暗黑模式切换按钮 |
nextThemes | 对象 | next-themes 包的配置 |
主题颜色
你可以通过为浅色和暗黑主题设置主要的色调和饱和度值来调整网站的主题颜色。
选项 | 类型 | 描述 |
---|---|---|
color.hue | 数字 | { dark: number; light: number } | 主要主题颜色的色调 |
color.saturation | 数字 | { dark: number; light: number } | 主要主题颜色的饱和度 |
backgroundColor.dark | 字符串 ,格式为 RRR,GGG,BBB | 浅色主题的背景颜色 |
backgroundColor.light | 字符串 ,格式为 RRR,GGG,BBB | 暗黑主题的背景颜色 |
试试看这个网站
色调 | 饱和度 |
---|---|
导航栏
Logo
在导航栏上渲染的网站 Logo。它可以是 React 节点或函数组件。
选项 | 类型 | 描述 |
---|---|---|
logo | React.ReactNode | React.FC | 网站的 Logo |
logoLink | 布尔值 | 字符串 | Logo 的链接 |
export default {
logo: (
<>
<svg width="24" height="24" viewBox="0 0 24 24">
<path
fill="currentColor"
d="M14.683 14.828a4.055 4.055 0 0 1-1.272.858a4.002 4.002 0 0 1-4.875-1.45l-1.658 1.119a6.063 6.063 0 0 0 1.621 1.62a5.963 5.963 0 0 0 2.148.903a6.035 6.035 0 0 0 3.542-.35a6.048 6.048 0 0 0 1.907-1.284c.272-.271.52-.571.734-.889l-1.658-1.119a4.147 4.147 0 0 1-.489.592z M12 2C6.486 2 2 6.486 2 12s4.486 10 10 10s10-4.486 10-10S17.514 2 12 2zm0 2c2.953 0 5.531 1.613 6.918 4H5.082C6.469 5.613 9.047 4 12 4zm0 16c-4.411 0-8-3.589-8-8c0-.691.098-1.359.264-2H5v1a2 2 0 0 0 2 2h2a2 2 0 0 0 2-2h2a2 2 0 0 0 2 2h2a2 2 0 0 0 2-2v-1h.736c.166.641.264 1.309.264 2c0 4.411-3.589 8-8 8z"
/>
</svg>
<span style={{ marginLeft: '.4em', fontWeight: 800 }}>
My Cool Project
</span>
</>
)
}
项目链接
显示一个按钮,该按钮在导航栏上链接到项目的首页。默认情况下,它链接到 Nextra 的 GitHub 仓库。
选项 | 类型 | 描述 |
---|---|---|
project.link | 字符串 | 项目首页的 URL |
project.icon | React.ReactNode | React.FC | 项目链接的图标或元素 |
你可以配置 project.link
和 project.icon
来自定义项目链接,例如使其链接到你的 GitLab 仓库
export default {
project: {
link: 'https://gitlab.com/inkscape/inkscape',
icon: (
<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.6a16.1 16.1 0 0 1-6.4-17.3L45 50a12 12 0 0 1 22.9-1.1L88.5 104h79l20.6-55.1A12 12 0 0 1 211 50l27.3 102.5a16.1 16.1 0 0 1-6.4 17.3Z" />
</svg>
)
}
}
如果缺少 icon
,则默认情况下它将是一个 GitHub 图标。
聊天链接
显示一个按钮,该按钮在导航栏上链接到项目的论坛或其他社交媒体。
选项 | 类型 | 描述 |
---|---|---|
chat.link | 字符串 | 聊天链接的 URL |
chat.icon | React.ReactNode | React.FC | 聊天链接的图标或元素 |
你可以配置 chat.link
和 chat.icon
来自定义聊天链接,例如使其链接到你的 Twitter 帐户
export default {
chat: {
link: 'https://twitter.com/shuding_',
icon: (
<svg width="24" height="24" viewBox="0 0 248 204">
<path
fill="currentColor"
d="M221.95 51.29c.15 2.17.15 4.34.15 6.53 0 66.73-50.8 143.69-143.69 143.69v-.04c-27.44.04-54.31-7.82-77.41-22.64 3.99.48 8 .72 12.02.73 22.74.02 44.83-7.61 62.72-21.66-21.61-.41-40.56-14.5-47.18-35.07a50.338 50.338 0 0 0 22.8-.87C27.8 117.2 10.85 96.5 10.85 72.46v-.64a50.18 50.18 0 0 0 22.92 6.32C11.58 63.31 4.74 33.79 18.14 10.71a143.333 143.333 0 0 0 104.08 52.76 50.532 50.532 0 0 1 14.61-48.25c20.34-19.12 52.33-18.14 71.45 2.19 11.31-2.23 22.15-6.38 32.07-12.26a50.69 50.69 0 0 1-22.2 27.93c10.01-1.18 19.79-3.86 29-7.95a102.594 102.594 0 0 1-25.2 26.16z"
/>
</svg>
)
}
}
如果缺少 icon
,则默认情况下它将是一个 Discord 图标。
菜单和自定义链接
查看 页面配置,了解如何向导航栏添加自定义菜单或链接。
搜索
选项 | 类型 | 描述 |
---|---|---|
search.component | React.ReactNode | React.FC<{ className?: string; directories: Item[] }> | |
search.emptyResult | React.ReactNode | React.FC | 未找到文本 |
search.loading | React.ReactNode | React.FC | 加载文本 |
search.error | 字符串 | (() => string) | 错误文本 |
search.placeholder | 字符串 | (() => string) | 占位符文本 |
横幅
在网站顶部显示横幅。它可以用于显示警告或通知。
选项 | 类型 | 描述 |
---|---|---|
banner.dismissible | 布尔值 | 是否可关闭横幅 |
banner.key | 字符串 | 用于保存横幅状态(已关闭或未关闭)的存储键 |
banner.content | React.ReactNode | React.FC | 横幅的内容 |
横幅键
横幅可以被关闭。默认情况下,banner.key
将为 "nextra-banner"
,并由 localStorage 用于在客户端保存横幅状态(已关闭或未关闭)。
如果你更新了横幅文本,则应更改键以确保再次显示横幅。最佳实践是始终为当前文本使用描述性键,例如
export default {
banner: {
key: '2.0-release',
content: (
<a href="https://nextra.nextjs.net.cn" target="_blank">
🎉 Nextra 2.0 is released. Read more →
</a>
)
}
}
自定义导航栏
自定义整个导航栏组件。
选项 | 类型 | 描述 |
---|---|---|
navbar.component | React.ReactNode | React.FC<NavBarProps> | 导航栏组件 |
navbar.extraContent | React.ReactNode | React.FC | 在最后一个图标之后显示额外内容 |
侧边栏
选项 | 类型 | 描述 |
---|---|---|
sidebar.defaultMenuCollapseLevel | 数字 | 指定左侧菜单默认折叠的文件夹级别。默认为 2 |
sidebar.autoCollapse | 布尔值 | 如果为 true,则自动折叠高于 defaultMenuCollapseLevel 的非活动文件夹 |
sidebar.toggleButton | 布尔值 | 隐藏/显示侧边栏切换按钮。默认为 false |
菜单折叠级别
默认情况下,侧边栏菜单在级别 2
处折叠。你可以通过将 sidebar.defaultMenuCollapseLevel
设置为不同的数字来更改它。例如,当设置为 1
时,每个文件夹都将默认折叠,而当设置为 Infinity
时,所有嵌套文件夹都将默认展开。
如果 sidebar.autoCollapse
设置为 true
,则所有不包含活动/焦点路由的文件夹将自动折叠到由 sidebar.defaultMenuCollapseLevel
设置的级别。例如,如果 defaultMenuCollapseLevel
为 2
,则顶级文件夹不会自动折叠。
自定义侧边栏内容
结合 分隔符 项目,您可以使用 JSX 元素来自定义侧边栏内容的渲染方式
export default {
index: 'Intro',
'--': {
type: 'separator',
title: (
<div className="flex items-center gap-2">
<MyLogo />
{children}
</div>
)
},
frameworks: 'JS Frameworks & Libs',
about: 'About'
}
使用前置 matter 自定义侧边栏
此外,您可以使用前置 matter 中的 sidebarTitle
属性来自定义侧边栏标题
---
sidebarTitle: Getting Started 🚀
---
侧边栏标题的优先级如下
_meta.js
文件中的title
属性- 前置 matter
sidebarTitle
- 前置 matter
title
- 使用 Title 格式化的页面文件名
内容
MDX 组件
提供自定义的 MDX 组件 来渲染内容。例如,您可以使用自定义的 pre
组件来渲染代码块。
选项 | 类型 | 描述 |
---|---|---|
组件 | Record<string, React.FC> | 自定义 MDX 组件 |
书写方向
网站的默认书写方向。
选项 | 类型 | 描述 |
---|---|---|
方向 | "ltr" | "rtl" | 默认书写方向 |
主要内容
渲染页面主要区域的顶部和/或底部内容。它可以用来渲染评论区、时事通讯表单或任何其他类型的页面内容。
选项 | 类型 | 描述 |
---|---|---|
主要 | React.FC<{ children: React.ReactNode }> | 主要内容组件 |
TOC 侧边栏
目录
在页面右侧显示目录。它有助于在标题之间导航。
选项 | 类型 | 描述 |
---|---|---|
toc.component | React.ReactNode | React.FC<TOCProps> | TOC 的自定义渲染器 |
toc.extraContent | React.ReactNode | React.FC | 在 TOC 内容下方显示额外内容 |
toc.float | 布尔值 | 将 TOC 悬浮在内容旁边 |
toc.title | React.ReactNode | React.FC | TOC 侧边栏的标题。默认情况下为“此页面上” |
toc.backToTop | React.ReactNode | React.FC | 滚动到顶部 按钮的文本 |
浮动 TOC
toc.float
默认启用。启用后,TOC 将显示在页面右侧,并且在滚动时将保持粘性。如果禁用,TOC 将直接显示在页面侧边栏上。
编辑链接
在页面上显示一个“编辑此页面”链接,该链接指向 GitHub(或其他位置)上的文件 URL。
选项 | 类型 | 描述 |
---|---|---|
editLink.content | React.ReactNode | React.FC | 编辑链接的内容 |
editLink.component | React.FC<{ children: React.ReactNode; className?: string; filePath?: string }> | null | 自定义编辑链接组件 |
要禁用它,您可以将 editLink.component
设置为 null
。
反馈链接
内置反馈链接为用户提供了一种提交有关文档的反馈的方式。默认情况下,它是一个指向文档存储库的问题创建表单的链接,其中预先填充了当前网站标题: 示例。
选项 | 类型 | 描述 |
---|---|---|
feedback.content | React.ReactNode | React.FC | 反馈按钮的内容 |
feedback.labels | 字符串 | 可以添加到新创建的 GitHub 问题的标签 |
feedback.useLink | () => string | 自定义链接,默认情况下,将在 docsRepositoryBase 中设置的存储库中打开一个问题 |
要禁用它,您可以将 feedback.content
设置为 null
。
页面末尾
导航
在内容底部显示上一页和下一页链接。它有助于在页面之间导航。
选项 | 类型 | 描述 |
---|---|---|
导航 | 布尔值 | 对象 | 启用或禁用导航链接 |
navigation.prev | 布尔值 | 启用或禁用上一页链接 |
navigation.next | 布尔值 | 启用或禁用下一页链接 |
export default {
navigation: {
prev: true,
next: true
}
}
以上也等效于 navigation: true
。
上次更新日期
显示每个页面的上次更新日期。它有助于显示内容的新鲜度。
选项 | 类型 | 描述 |
---|---|---|
gitTimestamp | React.ReactNode | React.FC<{ timestamp: Date }> | 渲染上次更新信息的组件 |
页脚
网站的页脚区域。您可以为默认页脚指定一些内容,也可以使用自定义组件完全自定义它。
选项 | 类型 | 描述 |
---|---|---|
footer.content | React.ReactNode | React.FC | 页脚组件的内容 |
footer.component | React.ReactNode | React.FC<{ menu: boolean }> | 自定义页脚组件 |
版权信息
您可以添加一些简单的内容,例如版权信息到默认页脚
export default {
footer: {
content: (
<span>
MIT {new Date().getFullYear()} ©{' '}
<a href="https://nextra.nextjs.net.cn" target="_blank">
Nextra
</a>
.
</span>
)
}
}
主题切换
选项 | 类型 | 描述 |
---|---|---|
themeSwitch.component | React.ReactNode | React.FC<{ lite?: boolean, className?: string }> | 渲染主题切换的组件 |
themeSwitch.useOptions | ThemeOptions | () => ThemeOptions | 主题切换中的选项 |
选项
您可以自定义选项名称以进行本地化或其他目的
export default {
themeSwitch: {
useOptions() {
return {
light: 'Light',
dark: 'Dark',
system: 'System'
}
}
}
}
未找到页面
配置未找到页面上损坏链接报告的选项。
选项 | 类型 | 描述 |
---|---|---|
notFound.content | ReactNode | FC | 默认值:提交有关损坏链接的问题 → |
notFound.labels | 字符串 | 默认值:bug |
国际化
配置语言下拉菜单的选项,用于 国际化文档网站。
选项 | 类型 | 描述 |
---|---|---|
i18n[number].locale | 字符串 | next.config 文件中 i18n.locales 字段中的语言环境 |
i18n[number].name | 字符串 | 下拉菜单中的语言环境名称 |
i18n[number].direction | 'ltr' | 'rtl' | 语言环境书写方向。默认值:ltr |
网站图标字形
这并非所有浏览器都支持,但它是一种通过简单地使用表情符号或字符来自定义网站网站图标的好方法。
选项 | 类型 | 描述 |
---|---|---|
faviconGlyph | 字符串 | 用作网站图标的字形 |