如何为单页API文档在Nextra导航栏添加锚点标签？

1. 定义嵌套锚点导航配置 #

放弃默认的_meta.js多页面配置，直接在API文档页面同级创建自定义导航文件（比如api-nav.js），按嵌套结构写好锚点信息：

export default [
  {
    label: 'API 概览',
    href: '#api-overview'
  },
  {
    label: '用户接口',
    items: [
      {
        label: '获取用户列表',
        href: '#get-user-list'
      },
      {
        label: '创建用户',
        href: '#create-user'
      }
    ]
  },
  {
    label: '订单接口',
    items: [
      {
        label: '查询订单',
        href: '#query-order'
      }
    ]
  }
]

2. 自定义Layout渲染嵌套导航 #

修改layout.jsx，导入上面的导航配置，替换默认Navbar或者在原有布局中加入自定义锚点导航区，同时处理锚点跳转的平滑滚动：

import { useRouter } from 'next/navigation'
import apiNav from './api-nav'

export default function APILayout({ children }) {
  const router = useRouter()

  const jumpToAnchor = (href) => {
    router.push(href, { scroll: false })
    setTimeout(() => {
      const target = document.querySelector(href)
      target?.scrollIntoView({ behavior: 'smooth' })
    }, 100)
  }

  const renderNav = (items) => {
    return items.map(item => (
      <div key={item.href || item.label} className="mb-2">
        {item.items ? (
          <div className="ml-2">
            <div className="font-semibold py-1">{item.label}</div>
            <div className="pl-2">{renderNav(item.items)}</div>
          </div>
        ) : (
          <button
            onClick={() => jumpToAnchor(item.href)}
            className="w-full text-left py-1 hover:text-blue-600"
            style={{ background: 'none', border: 'none', cursor: 'pointer' }}
          >
            {item.label}
          </button>
        )}
      </div>
    ))
  }

  return (
    <div className="flex">
      {/* 左侧自定义锚点导航 */}
      <aside className="w-64 border-r p-4 overflow-y-auto">
        {renderNav(apiNav)}
      </aside>
      {/* 文档内容 */}
      <main className="flex-1 p-8">{children}</main>
    </div>
  )
}

3. 配置Nextra与页面锚点 #

• 在next.config.js中确保Nextra开启App Router支持：

const withNextra = require('nextra')({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.jsx',
})

module.exports = withNextra({
  appDir: true,
})

• 在单页MDX文档里给每个章节指定锚点ID（Nextra也会自动根据标题生成slug锚点，比如## 获取用户列表会生成#获取用户列表的锚点，也可以手动指定）：

# API 概览 {#api-overview}

## 用户接口
### 获取用户列表 {#get-user-list}
接口地址：`GET /api/users`
请求参数：...

### 创建用户 {#create-user}
接口地址：`POST /api/users`
请求参数：...

## 订单接口
### 查询订单 {#query-order}
接口地址：`GET /api/orders/:id`
请求参数：...

4. 适配样式（可选） #

如果自定义导航和Nextra默认主题风格不一致，可添加CSS调整样式，让导航栏和默认Navbar视觉统一：

aside {
  height: 100vh;
  position: sticky;
  top: 0;
}

内容的提问来源于stack exchange，提问作者fgksnv43