自訂主題

Nextra 中的主題就像一個佈局，它將作為所有頁面的包裝器進行渲染。本文檔將引導您完成創建自定義主題的過程。

或者，您可以按照以下步驟部署一個範例並在其基礎上進一步構建

建立自訂主題

配置 Nextra 以使用主題

首先，您需要告知 Nextra 使用您的自定義主題文件而不是官方主題文件。在您的 Next.js 配置中，您可以將主題文件的路徑傳遞給 Nextra 插件

next.config.mjs

import nextra from 'nextra'
 
const withNextra = nextra({
  theme: './theme.tsx'
})
 
// If you have other Next.js configurations, you can pass them as the parameter:
// export default withNextra({ /* other next.js config */ })

建立基本主題

您現在可以開始製作您的主題了！在您的根目錄中，使用基本內容創建相應的 theme.tsx 文件

theme.tsx

import type { NextraThemeLayoutProps } from 'nextra'
 
export default function Layout({ children }: NextraThemeLayoutProps) {
  return (
    <div>
      <h1>My Theme</h1>
      <div style={{ border: '1px solid' }}>{children}</div>
    </div>
  )
}

它接受一個 children 屬性，它是當前頁面的 MDX 內容，並在內容周圍包裝一些其他元素。創建主題後，您可以簡單地添加一個 MDX 文件作為 pages/index.mdx 並查看結果

在您的主題佈局中，您可以使用 CSS 導入或其他方式來設置樣式。Next.js hooks，例如 useRouter、Head 也可用。

渲染活動頁面的元數據

除了 children 之外，一些其他有用的屬性也會傳遞給主題佈局。通過 pageOpts 屬性，主題可以訪問頁面的元信息。

例如，讓我們實現這些功能

在 <title> 中渲染頁面標題
通過 MDX <Wrapper> 組件顯示一個簡單的目錄
通過 front matter 為 og:image 添加一個 meta 標籤

theme.tsx

import Head from 'next/head'
import type { NextraThemeLayoutProps } from 'nextra'
import { MDXProvider } from 'nextra/mdx'
 
export default function Layout({ children, pageOpts }: NextraThemeLayoutProps) {
  const { title, frontMatter } = pageOpts
 
  return (
    <>
      <Head>
        <title>{title}</title>
        <meta name="og:image" content={frontMatter.image} />
      </Head>
      <MDXProvider components={{ wrapper: MyWrapper }}>{children}</MDXProvider>
    </>
  )
}
 
function MyWrapper({ children, toc }) {
  return (
    <>
      <h1>My Theme</h1>
      Table of Contents:
      <ul>
        {toc.map(heading => (
          <li key={heading.value}>{heading.value}</li>
        ))}
      </ul>
      <div style={{ border: '1px solid' }}>{children}</div>
    </>
  )
}

使用整個網站的頁面地圖

現在，如果您想渲染側邊欄或導航欄之類的東西，它不僅依賴於當前頁面的信息，還依賴於其他頁面的信息，您可以使用 pageMap 值。

例如，我們可以使用頂層中的所有頁面渲染一個簡單的導航列表

theme.tsx

import Link from 'next/link'
import type { NextraThemeLayoutProps } from 'nextra'
 
export default function Layout({ children, pageOpts }: NextraThemeLayoutProps) {
  const { pageMap } = pageOpts
 
  return (
    <div>
      <h1>My Theme</h1>
      {pageMap.map(item => {
        if ('route' in item && !('children' in item)) {
          return (
            <Link key={item.name} href={item.route}>
              {item.route}
            </Link>
          )
        }
      })}
      <div style={{ border: '1px solid' }}>{children}</div>
    </div>
  )
}

還有其他項目種類，例如 Folder（用於目錄）和 Meta（用於 _meta.js 文件）。所有項目都已類型化，因此您可以輕鬆了解屬性。

進階用法

⚠️

進階用法的文檔正在構建中。

開始使用