佈景主題設定
佈景主題是透過 theme.config.jsx 檔案設定的。它應該匯出一個包含您的設定的物件,例如
export default {
project: {
link: 'https://github.com/shuding/nextra'
},
logo: <b>Project</b>
}
以下是每個選項的詳細資訊。
全域
文件庫
設定文件庫的 URL。它用於產生「編輯此頁面」連結和「意見回饋」連結。
選項 | 類型 | 說明 |
---|---|---|
docsRepositoryBase | 字串 | 文件庫的 URL |
指定路徑
如果文件位於 monorepo、子資料夾或儲存庫的不同分支中,您可以簡單地將 docsRepositoryBase
設定為文件 pages/
資料夾的根路徑。例如
export default {
docsRepositoryBase: 'https://github.com/shuding/nextra/tree/main/docs'
}
然後 Nextra 將自動為所有頁面產生正確的檔案路徑。
Head 標籤
設定網站的 <head>
標籤。您可以新增 meta 標籤、標題、網站圖示等。
選項 | 類型 | 說明 |
---|---|---|
head | React.ReactNode | React.FC | 渲染 <head> 內容的元件 |
靜態 Head 標籤
如果您只有靜態 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
,根據目前頁面的 front matter 動態產生 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
hook 和 frontMatter
物件的資訊。
深色模式和佈景主題
自訂網站的佈景主題行為。
選項 | 類型 | 說明 |
---|---|---|
darkMode | 布林值 | 顯示或隱藏深色模式切換按鈕 |
nextThemes | 物件 | next-themes 套件的設定 |
佈景主題顏色
您可以透過設定淺色和深色佈景主題的主要色調和飽和度值來調整網站的佈景主題顏色。
選項 | 類型 | 說明 |
---|---|---|
color.hue | 數字 | { dark: 數字; light: 數字 } | 主要佈景主題顏色的色調 |
color.saturation | 數字 | { dark: 數字; light: 數字 } | 主要佈景主題顏色的飽和度 |
backgroundColor.dark | 格式為 RRR,GGG,BBB 的 字串 | 淺色佈景主題的背景顏色 |
backgroundColor.light | 格式為 RRR,GGG,BBB 的 字串 | 深色佈景主題的背景顏色 |
在此網站上試用
色調 | 飽和度 |
---|---|
導覽列
標誌
渲染在導覽列上的網站標誌。它可以是 React 節點或函式元件。
選項 | 類型 | 說明 |
---|---|---|
logo | React.ReactNode | React.FC | 網站的標誌 |
logoLink | 布林值 | 字串 | 標誌的連結 |

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 | (() => string) | 錯誤文字 |
search.placeholder | string | (() => 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.dev.org.tw" 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'
}

使用 Frontmatter 自訂側邊欄
此外,您可以在 front matter 中使用 sidebarTitle
屬性自訂側邊欄標題
---
sidebarTitle: Getting Started 🚀
---
側邊欄標題的優先順序如下:
_meta.js
檔案中的title
屬性- Front matter 中的
sidebarTitle
- Front matter 中的
title
- 使用 Title 格式化的頁面檔名
內容
MDX 元件
提供自訂 MDX 元件 來呈現內容。例如,您可以使用自訂的 pre
元件來呈現程式碼區塊。
選項 | 類型 | 說明 |
---|---|---|
components | Record<string, React.FC> | 自訂 MDX 元件 |
寫作方向
網站的預設寫作方向。
選項 | 類型 | 說明 |
---|---|---|
direction | "ltr" | "rtl" | 預設寫作方向 |
主要內容
渲染頁面主要區域的頂部和/或底部內容。它可以用於渲染評論區、電子報表單或任何其他類型的內容。
選項 | 類型 | 說明 |
---|---|---|
main | React.FC<{ children: React.ReactNode }> | 主要內容的元件 |
目錄側邊欄
目錄
在頁面右側顯示目錄。這對於在標題之間導航很有用。
選項 | 類型 | 說明 |
---|---|---|
toc.component | React.ReactNode | React.FC<TOCProps> | 目錄的自訂渲染器 |
toc.extraContent | React.ReactNode | React.FC | 在目錄內容下方顯示額外內容 |
toc.float | 布林值 | 將目錄浮動到內容旁邊 |
toc.title | React.ReactNode | React.FC | 目錄側邊欄的標題。預設為「在本頁面上」 |
toc.backToTop | React.ReactNode | React.FC | 捲動到頂部 按鈕的文字 |
浮動目錄
toc.float
預設為啟用。啟用後,目錄將顯示在頁面右側,並在捲動時保持黏性。如果停用,目錄將直接顯示在頁面側邊欄上。
編輯連結
在頁面上顯示「編輯此頁面」連結,指向 GitHub(或其他地方)上的檔案網址。
選項 | 類型 | 說明 |
---|---|---|
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 | boolean | object | 啟用或停用導覽連結 |
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.dev.org.tw" 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)
用於設定 多國語言文件網站 語言下拉選單的選項。
選項 | 類型 | 說明 |
---|---|---|
i18n[number].locale | 字串 | 來自 next.config 檔案中 i18n.locales 欄位的語系 |
i18n[number].name | 字串 | 下拉選單中的語系名稱 |
i18n[number].direction | 'ltr' | 'rtl' | 語系寫作方向。預設值:ltr |
網站圖示字元
並非所有瀏覽器都支援此功能,但這是一種只需使用表情符號或字元即可自訂網站網站圖示的好方法。
選項 | 類型 | 說明 |
---|---|---|
faviconGlyph | 字串 | 要用作網站圖示的字元 |