主题配置
主题通过 theme.config.jsx 文件进行配置。 应该对外暴露一个包含你的配置的对象,例如
export default {
project: {
link: 'https://github.com/shuding/nextra'
},
logo: <b>Project</b>
}
下面列出了主题配置每个选项的详细信息。
全局配置
docsRepositoryBase 文档存储库
设置文档的存储库URL。它用于生成“编辑此页面”链接和“反馈”链接。
Option | Type | Description |
---|---|---|
docsRepositoryBase | string | 文档存储库的URL |
指定特殊路径
如果文档位于单一存储库、子文件夹或存储库的不同分支中,你可以将docsRepositoryBase
简单地设置为你的文档pages/
文件夹的根路径。例如:
export default {
docsRepositoryBase: 'https://github.com/shuding/nextra/tree/main/docs'
}
然后 Nextra 将自动为所有页面生成正确的文件路径。
SEO 选项
你可以通过useNextSeoProps
选项配置与SEO相关的设置。
useNextSeoProps
函数返回将传递给Next SEO (opens in a new tab)组件的props。
它也是一个钩子,因此你可以在内部使用像useRouter
这样的API有条件地返回值。
Option | Type | Description |
---|---|---|
useNextSeoProps | () => NextSeoProps | 一个 React 钩子函数,用于返回 Next SEO 的选项。 |
例如,我们可以让所有页面呈现相同的后缀 <title>
:
export default {
useNextSeoProps() {
return {
titleTemplate: '%s – SWR'
}
}
}
%s
是一个 占位符 (opens in a new tab)
,将替换为页面标题。
您也可以为其设置条件,以避免将后缀添加到主页:
import { useRouter } from 'next/router'
export default {
useNextSeoProps() {
const { asPath } = useRouter()
if (asPath !== '/') {
return {
titleTemplate: '%s – SWR'
}
}
}
}
头部标签
配置网站的<head>
标签。你可以添加meta标签、title、favicon等。
Option | Type | Description |
---|---|---|
head | React.ReactNode | React.FC | Component that renders the <head> content. |
静态头部标签
如果你只有静态的头部标签,可以直接放置在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" />
</>
)
}
基于页面动态标签
你也可以将一个 function component 作为head
,根据当前页面的前置信息动态生成头部标签。例如:
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
对象的更多信息。
夜间模式和主题
自定义网站的主题行为。
Option | Type | Description |
---|---|---|
darkMode | boolean | 显示或隐藏深色模式切换按钮。 |
nextThemes | object | 配置 next-themes (opens in a new tab) 包. |
主题颜色
你可以通过设置浅色和深色主题的主要色调和饱和度值来调整网站的主题颜色。
Option | Type | Description |
---|---|---|
primaryHue | number | { dark: number; light: number } | 主要主题颜色的色调。 |
primarySaturation | number | { dark: number; light: number } | 主要主题颜色的饱和度。 |
试试这个:
Hue | Saturation |
---|---|
|
|
导航栏
标志
在导航栏上呈现的网站标志。它可以是一个React节点或一个函数组件。
Option | Type | Description |
---|---|---|
logo | React.ReactNode | React.FC | 网站Logo |
logoLink | boolean | string | 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 存储库。
Option | Type | Description |
---|---|---|
project.link | string | 主页的URL |
project.icon | React.ReactNode | React.FC | 项目链接的Icon |
你可以配置project.link
和project.icon
来自定义项目链接,例如将其链接到你的 GitLab 存储库:
export default {
project: {
link: 'https://gitlab.com/inkscape/inkscape',
icon: (
<svg width="24" height="24" viewBox="0 0 256 256">
<path
fill="currentColor"
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"
></path>
</svg>
)
}
}
如果icon
缺失,它将默认为GitHub图标 (opens in a new tab)。
聊天链接
在导航栏上显示一个按钮,该按钮链接到你项目的论坛或其他社交媒体。
Option | Type | Description |
---|---|---|
chat.link | string | 聊天链接的 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图标。
菜单和自定义链接
查看页面配置以了解如何将自定义菜单或链接添加到导航栏。
搜索
Option | Type | Description |
---|---|---|
search.component | React.ReactNode | React.FC<{ className?: string directories: Item[] }> | |
search.emptyResult | React.ReactNode | React.FC | Not found text |
search.loading | React.ReactNode | React.FC | Loading text |
search.error | string | (() => string) | Error text |
search.placeholder | string | (() => string) | 占位符文本 |
横幅
在网站顶部显示一个横幅。它可以用于显示警告或通知。
Option | Type | Description |
---|---|---|
banner.dismissible | boolean | Closable banner or not. |
banner.key | string | Storage key to keep the banner state (dismissed or not). |
banner.text | React.ReactNode | React.FC | Text of the banner. |
横幅键
横幅可以被关闭。默认情况下,banner.key
将为"nextra-banner"
,
并且它由localStorage (opens in a new tab)用于在客户端保存横幅状态(已关闭或未关闭)。
如果你已更新了横幅文本,你应该更改键以确保横幅再次显示。最佳做法是始终为当前文本使用一个描述性的键,例如:
export default {
banner: {
key: '2.0-release',
text: (
<a href="https://nextra.site" target="_blank">
🎉 Nextra 2.0 is released. Read more →
</a>
)
}
}
自定义导航栏
自定义整个导航栏组件。
Option | Type | Description |
---|---|---|
navbar.component | React.ReactNode | React.FC<NavBarProps> | Navbar 组件. |
navbar.extraContent | React.ReactNode | React.FC | 在最后一个图标后显示额外内容。 |
侧边栏
Option | Type | Description |
---|---|---|
sidebar.defaultMenuCollapseLevel | number | Specifies the folder level at which the menu on the left is collapsed by default. Defaults to 2. |
sidebar.autoCollapse | boolean | If true, automatically collapse inactive folders above defaultMenuCollapseLevel. |
sidebar.titleComponent | React.ReactNode | React.FC<{ type: string; title: string; route: string; }> | Custom renderer for sidebar titles. |
sidebar.toggleButton | boolean | Hide/show sidebar toggle button. Defaults to `false`. |
菜单折叠级别
默认情况下,侧边栏菜单在级别2
处折叠。你可以通过设置sidebar.defaultMenuCollapseLevel
来更改它为不同的数字。
例如,当设置为1
时,每个文件夹将默认折叠,当设置为Infinity
时,所有嵌套文件夹将默认展开。
如果sidebar.autoCollapse
设置为true
,那么所有不包含活动/焦点路由的文件夹将自动折叠到由sidebar.defaultMenuCollapseLevel
设置的级别。
例如,如果defaultMenuCollapseLevel
是2
,则顶级文件夹将不会自动折叠。
自定义侧边栏内容
结合分隔符项目,你可以使用sidebar.titleComponent
选项来自定义侧边栏内容的呈现方式:
export default {
sidebar: {
titleComponent({ title, type }) {
if (type === 'separator') {
return (
<div style={{ background: 'cyan', textAlign: 'center' }}>{title}</div>
)
}
if (title === 'About') {
return <>❓ {title}</>
}
return <>👉 {title}</>
}
}
}
内容
MDX 组件
提供自定义MDX组件 (opens in a new tab)来渲染内容。
例如,您可以使用自定义的 pre
组件来渲染代码块。
Option | Type | Description |
---|---|---|
components | Record<string, React.FC> | 自定义 MDX 组件. |
书写方向
网站的默认书写方向。
Option | Type | Description |
---|---|---|
direction | "ltr" | "rtl" | 默认书写方向 |
主要内容
渲染页面主区域顶部和/或底部的内容。它可以用来渲染评论区、通讯表单或任何其他类型的内容。
Option | Type | Description |
---|---|---|
main | React.FC<{ children: React.ReactNode }> | Component of main content. |
目录侧边栏
目录
在页面右侧显示目录。这对于在标题之间导航很有用。
Option | Type | Description |
---|---|---|
toc.component | React.ReactNode | React.FC<TOCProps> | Custom renderer of the TOC. |
toc.extraContent | React.ReactNode | React.FC | Display extra content below the TOC content. |
toc.float | boolean | Float the TOC next to the content. |
toc.title | React.ReactNode | React.FC | Title of the TOC sidebar. By default it’s “On This Page”. |
toc.headingComponent | React.FC<{ id: string, children: string }> | Custom renderer of TOC headings. |
toc.backToTop | boolean | Add `Scroll to top` link. |
悬浮式目录
默认情况下启用 toc.float
。启用后,目录将显示在页面右侧,并且在滚动时会固定在页面上。
如果禁用了,目录将直接显示在页面侧边栏上。
编辑链接
在页面上显示一个指向GitHub文件URL(或其他地方)的“编辑此页面”链接。
Option | Type | Description |
---|---|---|
editLink.text | React.ReactNode | React.FC | Content of the default edit link. |
editLink.component | React.FC<{ children: React.ReactNode className?: string filePath?: string }> | null | Customized edit link component. |
要禁用它,您可以将 editLink.component
设置为 null
。
反馈链接
内置的反馈链接提供了一种让用户提交关于文档的反馈的方式。默认情况下,它是一个指向文档存储库的问题创建表单的链接,当前网站标题会被预先填充: 示例 (opens in a new tab)。
Option | Type | Description |
---|---|---|
feedback.content | React.ReactNode | React.FC | Content of the feedback button. |
feedback.labels | string | Labels that can be added to the new created GitHub issue. |
feedback.useLink | () => string | Custom link, by default, will open an issue in the repository set in `docsRepositoryBase`. |
To disable it, you can set feedback.content
to null
.
页面底部
导航
在内容底部显示上一页和下一页的链接。这对于在页面之间导航很有用。
Option | Type | Description |
---|---|---|
navigation | boolean | object | Enable or disable navigation link. |
navigation.prev | boolean | Enable or disable the previous page link. |
navigation.next | boolean | Enable or disable the next page link. |
export default {
navigation: {
prev: true,
next: true
}
}
上述内容也等同于 navigation: true
。
最后更新日期
显示每个页面的最后更新日期。这对于展示内容的新鲜度很有用。
Option | Type | Description |
---|---|---|
gitTimestamp | React.ReactNode | React.FC<{ timestamp: Date }> | Component to render the last updated info. |
页脚
网站的页脚区域。您可以为默认页脚指定一些内容,也可以使用自定义组件完全自定义它。
Option | Type | Description |
---|---|---|
footer.text | React.ReactNode | React.FC | Content of the default footer component. |
footer.component | React.ReactNode | React.FC<{ menu: boolean }> | Customized footer component. |
版权信息
您可以向默认页脚添加一些简单的内容,例如版权信息:
export default {
footer: {
text: (
<span>
MIT {new Date().getFullYear()} ©{' '}
<a href="https://nextra.site" target="_blank">
Nextra
</a>
.
</span>
)
}
}
主题开关
Option | Type | Description |
---|---|---|
themeSwitch.component | React.ReactNode | React.FC<{ lite?: boolean, className?: string }> | Component to render the theme switch. |
themeSwitch.useOptions | ThemeOptions | () => ThemeOptions | Options in the theme switch. |
选项
您可以自定义选项名称以用于本地化或其他目的:
export default {
themeSwitch: {
useOptions() {
return {
light: 'Light',
dark: 'Dark',
system: 'System'
}
}
}
}
错误页面
404 - 未找到页面
500 - 内部服务器错误
Favicon图标(实验性)
这并不是所有浏览器都支持的功能,但通过使用表情符号或字符,这是一种简单的定制网站favicon的方法。
Option | Type | Description |
---|---|---|
faviconGlyph | string | The glyph to use as the favicon. |