Nextra 3.0 已發布。 閱讀更多
文件文件佈景主題佈景主題設定

佈景主題設定

佈景主題是透過 theme.config.jsx 檔案設定的。它應該匯出一個包含您的設定的物件,例如

theme.config.jsx
export default {
  project: {
    link: 'https://github.com/shuding/nextra'
  },
  logo: <b>Project</b>
}

以下是每個選項的詳細資訊。

全域

文件庫

設定文件庫的 URL。它用於產生「編輯此頁面」連結和「意見回饋」連結。

選項類型說明
docsRepositoryBase字串文件庫的 URL

指定路徑

如果文件位於 monorepo、子資料夾或儲存庫的不同分支中,您可以簡單地將 docsRepositoryBase 設定為文件 pages/ 資料夾的根路徑。例如

theme.config.jsx
export default {
  docsRepositoryBase: 'https://github.com/shuding/nextra/tree/main/docs'
}

然後 Nextra 將自動為所有頁面產生正確的檔案路徑。

Head 標籤

設定網站的 <head> 標籤。您可以新增 meta 標籤、標題、網站圖示等。

選項類型說明
headReact.ReactNode | React.FC渲染 <head> 內容的元件

靜態 Head 標籤

如果您只有靜態 head 標籤,可以直接將它們放在 head 中。例如

theme.config.jsx
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 標籤。例如

theme.config.jsx
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 節點或函式元件。

選項類型說明
logoReact.ReactNode | React.FC網站的標誌
logoLink布林值 | 字串標誌的連結
Customized Logo
theme.config.jsx
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.iconReact.ReactNode | React.FC專案連結的圖示或元素

您可以設定 project.linkproject.icon來自訂專案連結,例如將其連結到您的 GitLab 儲存庫

Project link
theme.config.jsx
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.iconReact.ReactNode | React.FC聊天連結的圖示或元素

您可以設定 chat.linkchat.icon來自訂聊天連結,例如將其連結到您的 Twitter 帳戶

theme.config.jsx
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.componentReact.ReactNode |
React.FC<{ className?: string; directories: Item[] }>
search.emptyResultReact.ReactNode | React.FC找不到文字
search.loadingReact.ReactNode | React.FC載入中文字
search.errorstring | (() => string)錯誤文字
search.placeholderstring | (() => string)預留位置文字

在網站頂部顯示橫幅。它可以用於顯示警告或通知。

選項類型說明
banner.dismissible布林值可關閉的橫幅或否
banner.key字串用於保留橫幅狀態(已關閉或未關閉)的儲存鍵值
banner.contentReact.ReactNode | React.FC橫幅的內容

可以關閉橫幅。預設情況下,banner.key 將是 "nextra-banner",並且 localStorage 使用它來保留客戶端上的橫幅狀態(已關閉或未關閉)。

如果您已更新橫幅文字,則應更改鍵值以確保再次顯示橫幅。最佳做法是始終對目前文字使用描述性鍵值,例如

Banner
theme.config.jsx
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.componentReact.ReactNode | React.FC<NavBarProps>導覽列元件
navbar.extraContentReact.ReactNode | React.FC在最後一個圖示後顯示額外內容
選項類型說明
sidebar.defaultMenuCollapseLevel數字指定預設情況下左側選單摺疊的資料夾級別。預設值為 2
sidebar.autoCollapse布林值如果為 true,則自動摺疊 defaultMenuCollapseLevel 以上非活躍的資料夾
sidebar.toggleButton布林值隱藏/顯示側邊欄切換按鈕。預設為 false

預設情況下,側邊欄選單在層級 2 處摺疊。您可以透過將 sidebar.defaultMenuCollapseLevel 設定為不同的數字來更改它。例如,當設定為 1 時,每個資料夾預設都會摺疊;當設定為 Infinity 時,所有巢狀資料夾預設都會展開。

如果 sidebar.autoCollapse 設定為 true,則所有不包含活躍/焦點路由的資料夾都會自動摺疊到 sidebar.defaultMenuCollapseLevel 設定的層級。例如,如果 defaultMenuCollapseLevel2,則頂層資料夾不會自動摺疊。

自訂側邊欄內容

搭配分隔符號項目,您可以使用 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

使用 Frontmatter 自訂側邊欄

此外,您可以在 front matter 中使用 sidebarTitle 屬性自訂側邊欄標題

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

側邊欄標題的優先順序如下:

  1. _meta.js 檔案中的 title 屬性
  2. Front matter 中的 sidebarTitle
  3. Front matter 中的 title
  4. 使用 Title 格式化的頁面檔名

內容

MDX 元件

提供自訂 MDX 元件 來呈現內容。例如,您可以使用自訂的 pre 元件來呈現程式碼區塊。

選項類型說明
componentsRecord<string, React.FC>自訂 MDX 元件

寫作方向

網站的預設寫作方向。

選項類型說明
direction"ltr" | "rtl"預設寫作方向

主要內容

渲染頁面主要區域的頂部和/或底部內容。它可以用於渲染評論區、電子報表單或任何其他類型的內容。

選項類型說明
mainReact.FC<{ children: React.ReactNode }>主要內容的元件

目錄側邊欄

目錄

在頁面右側顯示目錄。這對於在標題之間導航很有用。

選項類型說明
toc.componentReact.ReactNode | React.FC<TOCProps>目錄的自訂渲染器
toc.extraContentReact.ReactNode | React.FC在目錄內容下方顯示額外內容
toc.float布林值將目錄浮動到內容旁邊
toc.titleReact.ReactNode | React.FC目錄側邊欄的標題。預設為「在本頁面上」
toc.backToTopReact.ReactNode | React.FC捲動到頂部 按鈕的文字

浮動目錄

toc.float 預設為啟用。啟用後,目錄將顯示在頁面右側,並在捲動時保持黏性。如果停用,目錄將直接顯示在頁面側邊欄上。

在頁面上顯示「編輯此頁面」連結,指向 GitHub(或其他地方)上的檔案網址。

選項類型說明
editLink.contentReact.ReactNode | React.FC編輯連結的內容
editLink.componentReact.FC<{ children: React.ReactNode; className?: string; filePath?: string }> | null自訂的編輯連結元件

要停用它,您可以將 editLink.component 設定為 null

內建的意見回饋連結提供使用者提交關於文件的意見回饋的方式。預設情況下,它是一個指向文件庫問題建立表單的連結,其中預先填寫了目前的網站標題:範例

選項類型說明
feedback.contentReact.ReactNode | React.FC意見回饋按鈕的內容
feedback.labels字串可以添加到新建立的 GitHub 問題的標籤
feedback.useLink() => string自訂連結,預設情況下,將在 docsRepositoryBase 中設定的儲存庫中開啟一個問題

要停用它,您可以將 feedback.content 設定為 null

頁面結尾

在內容底部顯示上一頁和下一頁連結。這對於在頁面之間導航很有用。

選項類型說明
navigationboolean | object啟用或停用導覽連結
navigation.prev布林值啟用或停用上一頁連結
navigation.next布林值啟用或停用下一頁連結
Navigation
theme.config.jsx
export default {
  navigation: {
    prev: true,
    next: true
  }
}

以上設定等同於 navigation: true

上次更新日期

顯示每個頁面的上次更新日期。這對於顯示內容的新鮮度很有用。

選項類型說明
gitTimestampReact.ReactNode | React.FC<{ timestamp: Date }>用於呈現上次更新資訊的元件

網站的頁尾區域。您可以為預設頁尾指定一些內容,也可以使用自訂元件完全自訂它。

選項類型說明
footer.contentReact.ReactNode | React.FC頁尾元件的內容
footer.componentReact.ReactNode | React.FC<{ menu: boolean }>自訂的頁尾元件

您可以在預設頁尾中添加一些簡單的內容,例如版權資訊

theme.config.jsx
export default {
  footer: {
    content: (
      <span>
        MIT {new Date().getFullYear()} ©{' '}
        <a href="https://nextra.dev.org.tw" target="_blank">
          Nextra
        </a>
        .
      </span>
    )
  }
}

主題切換

選項類型說明
themeSwitch.componentReact.ReactNode |
React.FC<{ lite?: boolean, className?: string }>
用於呈現主題切換的元件
themeSwitch.useOptionsThemeOptions | () => ThemeOptions主題切換中的選項

選項

您可以自訂選項名稱以進行在地化或其他用途

theme.config.jsx
export default {
  themeSwitch: {
    useOptions() {
      return {
        light: 'Light',
        dark: 'Dark',
        system: 'System'
      }
    }
  }
}

找不到頁面

用於設定在找不到頁面上回報失效連結的選項。

選項類型說明
notFound.contentReactNode | FC預設值:提交關於失效連結的問題 →
notFound.labels字串預設值:bug

多國語言 (I18n)

用於設定 多國語言文件網站 語言下拉選單的選項。

選項類型說明
i18n[number].locale字串來自 next.config 檔案中 i18n.locales 欄位的語系
i18n[number].name字串下拉選單中的語系名稱
i18n[number].direction'ltr' | 'rtl'語系寫作方向。預設值:ltr

網站圖示字元

並非所有瀏覽器都支援此功能,但這是一種只需使用表情符號或字元即可自訂網站網站圖示的好方法。

選項類型說明
faviconGlyph字串要用作網站圖示的字元