Nextra 学习指南

# 使用 create-nextra-app
npx create-nextra-app@latest my-docs
 
# 手动创建
npx create-next-app@latest my-docs --typescript --tailwind --eslint
cd my-docs
npm install nextra nextra-theme-docs

my-docs/
├── pages/              # 页面目录
│   ├── _meta.json      # 导航配置
│   ├── index.mdx       # 首页
│   ├── guide/
│   │   ├── _meta.json  # 子导航配置
│   │   ├── getting-started.mdx
│   │   └── advanced.mdx
│   └── api/
│       └── _meta.json
├── components/         # 自定义组件
├── public/            # 静态资源
├── next.config.mjs    # Next.js 配置
├── nextra.config.mjs  # Nextra 配置
└── package.json

// pages/index.mdx - 首页 (/)
---
title: 欢迎使用 Nextra
description: 一个强大的文档站点生成器
---
 
# 欢迎使用 Nextra
 
Nextra 是一个基于 Next.js 的静态站点生成器，专门用于构建文档网站。
 
## 特性
 
- 📝 **MDX 支持** - 在 Markdown 中使用 React 组件
- 🎨 **主题系统** - 丰富的主题和自定义选项
- 🔍 **搜索功能** - 内置全文搜索
- 📱 **响应式设计** - 完美适配各种设备
- ⚡ **快速构建** - 基于 Next.js 的高性能

// pages/guide/getting-started.mdx - 指南页面 (/guide/getting-started)
---
title: 快速开始
description: 学习如何快速搭建 Nextra 项目
---
 
# 快速开始
 
## 安装
 
```bash
npm install nextra nextra-theme-docs

import nextra from 'nextra'
 
const withNextra = nextra({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.jsx'
})
 
export default withNextra()

### 导航配置

```json
// pages/_meta.json - 根导航
{
  "index": "首页",
  "guide": "指南",
  "api": "API 参考",
  "about": "关于"
}

// pages/guide/_meta.json - 子导航
{
  "getting-started": "快速开始",
  "installation": "安装配置",
  "advanced": "高级用法",
  "deployment": "部署指南"
}

// pages/api/_meta.json - API 导航
{
  "index": "概述",
  "authentication": "认证",
  "endpoints": "接口列表"
}

// next.config.mjs
import nextra from 'nextra'
 
const withNextra = nextra({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.jsx',
  defaultShowCopyCode: true,
  flexsearch: {
    codeblocks: true
  },
  staticImage: true,
  readingTime: true
})
 
export default withNextra()

// theme.config.jsx
export default {
  logo: <span>My Documentation</span>,
  project: {
    link: 'https://github.com/your-repo'
  },
  docsRepositoryBase: 'https://github.com/your-repo/tree/main',
  footer: {
    text: 'MIT 2024 © Your Name.'
  },
  useNextSeoProps() {
    return {
      titleTemplate: '%s – My Docs'
    }
  },
  head: (
    <>
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <meta property="og:title" content="My Documentation" />
      <meta property="og:description" content="A comprehensive documentation site" />
    </>
  ),
  primaryHue: 210,
  primarySaturation: 100
}

// pages/features.mdx
---
title: 功能特性
---
 
# 功能特性
 
## 代码高亮
 
```javascript
function hello() {
  console.log('Hello, Nextra!')
}

### 自定义组件

```jsx
// components/Callout.jsx
export function Callout({ children, type = 'info' }) {
  const styles = {
    info: 'bg-blue-50 border-blue-200 text-blue-800',
    warning: 'bg-yellow-50 border-yellow-200 text-yellow-800',
    error: 'bg-red-50 border-red-200 text-red-800'
  }

  return (
    <div className={`p-4 border-l-4 rounded ${styles[type]}`}>
      {children}
    </div>
  )
}

// pages/guide/components.mdx
import { Callout } from '../../components/Callout'
 
# 使用自定义组件
 
<Callout type="info">
  这是一个信息提示框。
</Callout>
 
<Callout type="warning">
  这是一个警告提示框。
</Callout>
 
<Callout type="error">
  这是一个错误提示框。
</Callout>

// components/CodeBlock.jsx
import { useRouter } from 'next/router'
 
export function CodeBlock({ children, language, filename }) {
  const router = useRouter()
  
  return (
    <div className="my-4">
      {filename && (
        <div className="bg-gray-100 px-4 py-2 text-sm font-mono">
          {filename}
        </div>
      )}
      <pre className="bg-gray-900 text-white p-4 rounded-b overflow-x-auto">
        <code className={`language-${language}`}>
          {children}
        </code>
      </pre>
    </div>
  )
}

// next.config.mjs
const withNextra = nextra({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.jsx',
  flexsearch: {
    codeblocks: true,
    indexBy: 'content'
  },
  defaultShowCopyCode: true
})

// next.config.mjs
const withNextra = nextra({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.jsx',
  i18n: {
    locales: ['en', 'zh'],
    defaultLocale: 'en'
  }
})

// theme.config.jsx
export default {
  i18n: [
    { locale: 'en', text: 'English' },
    { locale: 'zh', text: '中文' }
  ],
  // ... 其他配置
}

// theme.config.jsx
export default {
  // 颜色配置
  primaryHue: 210,
  primarySaturation: 100,
  
  // 导航配置
  navigation: {
    prev: true,
    next: true
  },
  
  // 侧边栏配置
  sidebar: {
    defaultMenuCollapseLevel: 1,
    toggleButton: true
  },
  
  // 页脚配置
  footer: {
    text: (
      <span>
        MIT 2024 ©{' '}
        <a href="https://your-site.com" target="_blank">
          Your Name
        </a>
        .
      </span>
    )
  },
  
  // SEO 配置
  useNextSeoProps() {
    return {
      titleTemplate: '%s – My Documentation'
    }
  },
  
  // 头部配置
  head: (
    <>
      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
      <meta property="og:title" content="My Documentation" />
      <meta property="og:description" content="A comprehensive documentation site" />
      <link rel="icon" href="/favicon.ico" />
    </>
  )
}

# 安装语法高亮插件
npm install rehype-highlight
 
# 安装数学公式插件
npm install rehype-katex remark-math
 
# 安装图表插件
npm install rehype-mermaid

// next.config.mjs
import nextra from 'nextra'
 
const withNextra = nextra({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.jsx',
  mdxOptions: {
    remarkPlugins: [
      require('remark-math')
    ],
    rehypePlugins: [
      require('rehype-highlight'),
      require('rehype-katex'),
      require('rehype-mermaid')
    ]
  }
})
 
export default withNextra()

// plugins/custom-plugin.js
export function customPlugin() {
  return function transformer(tree) {
    // 处理 AST
    return tree
  }
}

// vercel.json
{
  "buildCommand": "npm run build",
  "outputDirectory": "out",
  "framework": "nextjs",
  "installCommand": "npm install"
}

# .github/workflows/deploy.yml
name: Deploy to GitHub Pages
 
on:
  push:
    branches: [main]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      - run: npm ci
      - run: npm run build
      - run: npm run export
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./out

# netlify.toml
[build]
  command = "npm run build"
  publish = "out"
 
[build.environment]
  NODE_VERSION = "18"
 
[[redirects]]
  from = "/*"
  to = "/index.html"
  status = 200