文档主题

Nextra 文档主题包含了构建现代文档网站所需的几乎所有内容。它包括：

顶部导航栏
搜索栏
页面侧边栏
目录（TOC）
以及其他内置组件

💡

Tip

本网站本身就是使用 Nextra 文档主题构建的。

作为新项目开始

安装

要手动创建 Nextra 文档站点，你需要安装 Next.js、React、Nextra 和 Nextra 文档主题。在你的项目目录中，运行以下命令来安装依赖：


npm i next react react-dom nextra nextra-theme-docs


pnpm add next react react-dom nextra nextra-theme-docs


yarn add next react react-dom nextra nextra-theme-docs


bun add next react react-dom nextra nextra-theme-docs

Note

如果你的项目中已经安装了 Next.js，你只需要安装 nextra 和 nextra-theme-docs 作为附加组件。

Add the following scripts to your package.json:

package.json


"scripts": {
  "dev": "next",
  "build": "next build",
  "start": "next start"
},

💡

Tip

You can enable Turbopack in development by appending the --turbopack flag to the dev command:

package.json


- "dev": "next",
+ "dev": "next --turbopack",

You can start the server in development mode with the following command according to your package manager:


npm run dev


pnpm run dev


yarn dev


bun run dev

or in production mode:


npm run build
npm run start


pnpm run build
pnpm run start


yarn build
yarn run start


bun run build
bun run start

Note

If you’re not familiar with Next.js, note that development mode is significantly slower since Next.js compiles every page you navigate to.

Add Next.js config

Create a next.config.mjs file in your project’s root directory with the following content:

next.config.mjs


import nextra from 'nextra'
 
const withNextra = nextra({
  // ... Other Nextra config options
})
 
// You can include other Next.js configuration options here, in addition to Nextra settings:
export default withNextra({
  // ... Other Next.js config options
})

With this configuration, Nextra will handle Markdown files in your Next.js project. For more Nextra configuration options, check out the Guide.

添加 `mdx-components` 文件

创建根布局

接下来，在 app 文件夹中创建应用程序的根布局。这个布局将用于配置 Nextra 文档主题：

app/layout.jsx


import { Footer, Layout, Navbar } from 'nextra-theme-docs'
import { Banner, Head } from 'nextra/components'
import { getPageMap } from 'nextra/page-map'
import 'nextra-theme-docs/style.css'
 
export const metadata = {
  // Define your metadata here
  // For more information on metadata API, see: https://nextjs.org/docs/app/building-your-application/optimizing/metadata
}
 
const banner = <Banner storageKey="some-key">Nextra 4.0 is released 🎉</Banner>
const navbar = (
  <Navbar
    logo={<b>Nextra</b>}
    // ... Your additional navbar options
  />
)
const footer = <Footer>MIT {new Date().getFullYear()} © Nextra.</Footer>
 
export default async function RootLayout({ children }) {
  return (
    <html
      // Not required, but good for SEO
      lang="en"
      // Required to be set
      dir="ltr"
      // Suggested by `next-themes` package https://github.com/pacocoursey/next-themes#with-app
      suppressHydrationWarning
    >
      <Head
      // ... Your additional head options
      >
        {/* Your additional tags should be passed as `children` of `<Head>` element */}
      </Head>
      <body>
        <Layout
          banner={banner}
          navbar={navbar}
          pageMap={await getPageMap()}
          docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs"
          footer={footer}
          // ... Your additional layout options
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}

Render MDX files

There are two ways to render MDX files using file-based routing, add your MDX files via page files or content directory convention.

Run the project

Run the dev command specified in package.json to start developing the project! 🎉


npm run dev


pnpm run dev


yarn dev


bun run dev

接下来，查看下一节以了解如何组织文档结构和配置网站主题。