文档主题
Nextra 文档主题是一个主题，它包含了构建现代文档网站所需的大部分内容。它包括：
- 顶级导航栏
- 搜索栏
- 页面侧边栏
- 目录（TOC）
- 以及其他内置组件
这个网站本身就是使用 Nextra 文档主题构建的。
作为新项目开始
安装
要手动创建一个 Nextra 文档站点，您需要安装 Next.js、React、Nextra 和 Nextra 文档主题。在您的项目目录中，运行以下命令来安装依赖项：
npm i next react react-dom nextra nextra-theme-docs如果您的项目中已经安装了 Next.js，您只需安装 nextra 和 nextra-theme-docs 作为附加组件。
Add the following scripts to your package.json:
"scripts": {
"dev": "next",
"build": "next build",
"start": "next start"
},You can enable Turbopack in development by appending the --turbopack flag to
the dev command:
- "dev": "next",
+ "dev": "next --turbopack",You can start the server in development mode with the following command according to your package manager:
npm run devor in production mode:
npm run build
npm run startIf 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:
import nextra from 'nextra'
// Set up Nextra with its configuration
const withNextra = nextra({
// ... Add Nextra-specific options here
})
// Export the final Next.js config with Nextra included
export default withNextra({
// ... Add regular Next.js options here
})With this configuration, Nextra will handle Markdown files in your Next.js project. For more Nextra configuration options, check out the Guide.
Add mdx-components file
Setup search
To set up search, follow the instructions on the Search Engine page.
Create the root layout
Next, create the root layout of your application inside the app folder. This
layout will be used to configure your Nextra Theme:
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 = {
// 在此处定义您的元数据
// 有关元数据 API 的更多信息，请参阅：https://nextjs.org/docs/app/building-your-application/optimizing/metadata
}
const banner = <Banner storageKey="some-key">Nextra 4.0 已发布 🎉</Banner>
const navbar = (
<Navbar
logo={<b>Nextra</b>}
// ... 您的其他导航栏选项
/>
)
const footer = <Footer>MIT {new Date().getFullYear()} © Nextra。</Footer>
export default async function RootLayout({ children }) {
return (
<html
// 非必需，但有利于 SEO
lang="en"
// 必须设置
dir="ltr"
// 由 `next-themes` 包建议 https://github.com/pacocoursey/next-themes#with-app
suppressHydrationWarning
>
<Head
// ... 您的其他 head 选项
>
{/* 您的其他标签应作为 `<Head>` 元素的 `children` 传递 */}
</Head>
<body>
<Layout
banner={banner}
navbar={navbar}
pageMap={await getPageMap()}
docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs"
footer={footer}
// ... 您的其他布局选项
>
{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