docs: add apps/docs Nextra implementation plan

Made-with: Cursor
2026-10-19 16:14:37 +00:00 · 2026-04-14 21:19:42 +08:00
parent bff4c9f905
commit 67f12dbf2c
1 changed files with 466 additions and 0 deletions
@@ -0,0 +1,466 @@
+# apps/docs（Nextra 4 文档站）实现计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 在 `apps/docs` 新增基于 **Next.js App Router + Nextra 4 + nextra-theme-docs** 的中文使用文档站，服务模板选型开发者（design spec：`docs/specs/2026-04-15-apps-docs-nextra-design.md`）。
+
+**Architecture:** `content/` 目录存放 MDX；`app/[[...mdxPath]]/page.tsx` 作为 Nextra 文档网关；`app/layout.tsx` 装配 Docs Theme；**首期不配置 `basePath`**（根路径部署）；与 `apps/basic`、`apps/with-lingui`（Vite+）并存。
+
+**Tech Stack:** Next.js 15+（App Router）、React 19、Nextra 4、`nextra-theme-docs`、TypeScript、pnpm workspace。
+
+---
+
+## 文件映射（新建为主）
+
+| 路径 | 职责 |
+|------|------|
+| `apps/docs/package.json` | 包名 `antd-admin-docs`，scripts：`dev`/`build`/`start`/`lint` |
+| `apps/docs/next.config.mjs` | `nextra()` 包装 Next 配置 |
+| `apps/docs/tsconfig.json` | TS 严格模式 + `paths`：`@/*` → `./*` |
+| `apps/docs/next-env.d.ts` | Next 类型三斜线引用 |
+| `apps/docs/mdx-components.tsx` | 必填：`useMDXComponents` 合并主题默认组件 |
+| `apps/docs/app/layout.tsx` | 根布局：`Layout`/`Navbar`/`Footer`/`Head`，`lang="zh-CN"`，`getPageMap()` |
+| `apps/docs/app/[[...mdxPath]]/page.tsx` | 动态 MDX 页：`importPage`、`generateStaticParamsFor` |
+| `apps/docs/content/index.mdx` | 首页文档 |
+| `apps/docs/content/quick-start.mdx` | 快速开始 |
+| `apps/docs/content/templates.mdx` | 模板对比（可含表格） |
+| `apps/docs/content/features.mdx` | 功能与约定（占位 + 链到各 app README） |
+| `apps/docs/content/configuration.mdx` | 配置参考（简短） |
+| `apps/docs/README.md` | 本地开发与端口说明 |
+| `turbo.json`（仓库根） | `build` 的 `outputs` 增加 `.next/**`（并可排除 cache，见 Task 7） |
+| `README.md`（仓库根） | Templates 小节增加文档站入口与端口 |
+| `pnpm-lock.yaml`（根） | `pnpm install` 后更新 |
+
+---
+
+### Task 1: 初始化 `apps/docs` 包与依赖
+
+**Files:**
+
+- Create: `apps/docs/package.json`
+- Modify: `pnpm-lock.yaml`（根目录，安装后）
+
+- [ ] **Step 1: 创建 `apps/docs/package.json`**
+
+内容示例（版本号在安装步骤用 CLI 解析为精确版本并写回 lockfile；此处用 `latest` 或 caret 作为起点）：
+
+```json
+{
+  "name": "antd-admin-docs",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev -p 3000",
+    "build": "next build",
+    "start": "next start -p 3000",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "next": "^15.1.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "nextra": "^4.0.0",
+    "nextra-theme-docs": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "~5.9.0",
+    "eslint": "^9.0.0",
+    "eslint-config-next": "^15.1.0"
+  }
+}
+```
+
+- [ ] **Step 2: 在仓库根安装**
+
+```bash
+cd /Users/zuiidea/web/antd-admin
+pnpm install
+```
+
+Expected: 退出码 0，`pnpm-lock.yaml` 更新。
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add apps/docs/package.json pnpm-lock.yaml
+git commit -m "chore(docs): scaffold antd-admin-docs package with Nextra deps"
+```
+
+---
+
+### Task 2: Next / TS 基础配置
+
+**Files:**
+
+- Create: `apps/docs/next.config.mjs`
+- Create: `apps/docs/tsconfig.json`
+- Create: `apps/docs/next-env.d.ts`
+
+- [ ] **Step 1: 写入 `apps/docs/next.config.mjs`**
+
+```javascript
+import nextra from "nextra";
+
+const withNextra = nextra({
+  defaultShowCopyCode: true,
+});
+
+export default withNextra({
+  reactStrictMode: true,
+});
+```
+
+（若启用 `next dev --turbopack` 且出现 `next-mdx-import-source-file` 解析错误，按 [Nextra mdx-components 文档](https://nextra.site/docs/file-conventions/mdx-components-file) 增加 `turbopack.resolveAlias`；**首期可不启用 turbopack** 以降低摩擦。）
+
+- [ ] **Step 2: 写入 `apps/docs/tsconfig.json`**
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "preserve",
+    "incremental": true,
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./*"] }
+  },
+  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "exclude": ["node_modules"]
+}
+```
+
+- [ ] **Step 3: 写入 `apps/docs/next-env.d.ts`**
+
+```typescript
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+```
+
+- [ ] **Step 4: 验证**
+
+```bash
+cd apps/docs && pnpm exec tsc --noEmit
+```
+
+Expected: 在补齐源码文件前可能失败；完成 Task 3–5 后再跑至通过。
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/docs/next.config.mjs apps/docs/tsconfig.json apps/docs/next-env.d.ts
+git commit -m "chore(docs): add Next and TypeScript config for Nextra"
+```
+
+---
+
+### Task 3: MDX 组件入口
+
+**Files:**
+
+- Create: `apps/docs/mdx-components.tsx`
+
+- [ ] **Step 1: 写入完整文件**
+
+```tsx
+import { useMDXComponents as getThemeComponents } from "nextra-theme-docs";
+import type { MDXComponents } from "mdx/types";
+
+const themeComponents = getThemeComponents();
+
+export function useMDXComponents(components: MDXComponents): MDXComponents {
+  return {
+    ...themeComponents,
+    ...components,
+  };
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add apps/docs/mdx-components.tsx
+git commit -m "feat(docs): add mdx-components for Nextra theme"
+```
+
+---
+
+### Task 4: 根布局（Docs Theme + 中文元数据）
+
+**Files:**
+
+- Create: `apps/docs/app/layout.tsx`
+
+- [ ] **Step 1: 写入完整文件**（按需替换 `docsRepositoryBase` 分支名）
+
+```tsx
+import { Footer, Layout, Navbar } from "nextra-theme-docs";
+import { Head } from "nextra/components";
+import { getPageMap } from "nextra/page-map";
+import "nextra-theme-docs/style.css";
+import type { Metadata } from "next";
+import type { ReactElement, ReactNode } from "react";
+
+export const metadata: Metadata = {
+  title: {
+    default: "Antd Admin 文档",
+    template: "%s – Antd Admin 文档",
+  },
+  description: "antd-admin 模板使用说明：basic 与 with-lingui 选型、安装与配置。",
+};
+
+const navbar = (
+  <Navbar
+    logo={<b>Antd Admin 文档</b>}
+    projectLink="https://github.com/zuiidea/antd-admin"
+  />
+);
+
+const footer = (
+  <Footer>
+    MIT {new Date().getFullYear()} ©{" "}
+    <a href="https://github.com/zuiidea/antd-admin" rel="noreferrer" target="_blank">
+      antd-admin
+    </a>
+  </Footer>
+);
+
+export default async function RootLayout({
+  children,
+}: {
+  children: ReactNode;
+}): Promise<ReactElement> {
+  const pageMap = await getPageMap();
+
+  return (
+    <html lang="zh-CN" dir="ltr" suppressHydrationWarning>
+      <Head />
+      <body>
+        <Layout
+          navbar={navbar}
+          pageMap={pageMap}
+          docsRepositoryBase="https://github.com/zuiidea/antd-admin/tree/master"
+          footer={footer}
+        >
+          {children}
+        </Layout>
+      </body>
+    </html>
+  );
+}
+```
+
+说明：未加官方示例里的 `Banner`，避免与正式文档抢视觉；若需要公告可后续再加。
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add apps/docs/app/layout.tsx
+git commit -m "feat(docs): Nextra docs theme root layout (zh-CN)"
+```
+
+---
+
+### Task 5: 动态 MDX 路由网关
+
+**Files:**
+
+- Create: `apps/docs/app/[[...mdxPath]]/page.tsx`
+
+- [ ] **Step 1: 写入完整文件**（`mdx-components` 相对路径：从 `app/[[...mdxPath]]/` 到项目根为 `../../`）
+
+```tsx
+import { generateStaticParamsFor, importPage } from "nextra/pages";
+import { useMDXComponents as getMDXComponents } from "../../mdx-components";
+
+export const generateStaticParams = generateStaticParamsFor("mdxPath");
+
+type PageProps = { params: Promise<{ mdxPath?: string[] }> };
+
+export async function generateMetadata(props: PageProps) {
+  const params = await props.params;
+  const { metadata } = await importPage(params.mdxPath);
+  return metadata;
+}
+
+export default async function Page(props: PageProps) {
+  const params = await props.params;
+  const {
+    default: MDXContent,
+    toc,
+    metadata,
+    sourceCode,
+  } = await importPage(params.mdxPath);
+
+  const Wrapper = getMDXComponents().wrapper;
+
+  return (
+    <Wrapper toc={toc} metadata={metadata} sourceCode={sourceCode}>
+      <MDXContent {...props} params={params} />
+    </Wrapper>
+  );
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add "apps/docs/app/[[...mdxPath]]/page.tsx"
+git commit -m "feat(docs): add Nextra catch-all MDX page"
+```
+
+---
+
+### Task 6: 中文内容骨架（≥ 3 个侧边栏条目）
+
+**Files:**
+
+- Create: `apps/docs/content/index.mdx`
+- Create: `apps/docs/content/quick-start.mdx`
+- Create: `apps/docs/content/templates.mdx`
+- Create: `apps/docs/content/features.mdx`
+- Create: `apps/docs/content/configuration.mdx`
+
+- [ ] **Step 1: 为每个文件添加 frontmatter 与标题**（示例：`index.mdx`）
+
+```mdx
+---
+title: 概述
+description: antd-admin monorepo 与模板说明
+---
+
+# 概述
+
+本仓库提供两个可运行模板：**`apps/basic`**（英文-only）与 **`apps/with-lingui`**（Lingui 中英文）。详细对比见「模板对比」。
+```
+
+- [ ] **Step 2:** `quick-start.mdx` 写清 Node ≥ 20、`vp`、分别 `cd apps/basic` / `cd apps/with-lingui` 安装与 `vp dev`，默认账号 `admin` / `admin`，并注明 **文档站** 使用 `cd apps/docs && pnpm dev`（端口 **3000**），与模板 **5173** 区分。
+
+- [ ] **Step 3:** `templates.mdx` 用 Markdown 表格对比：`package.json` 的 `name`、Lingui、Ant Design locale、Zustand persist key（`basic` 为 `settings-storage-basic` 等，以源码为准）。
+
+- [ ] **Step 4:** `features.mdx` / `configuration.mdx` 以短章节 + 指向各 app 内 README 或源码路径的链接为主，避免长篇双维护。
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add apps/docs/content
+git commit -m "docs(docs): add Chinese content skeleton for Nextra"
+```
+
+---
+
+### Task 7: Turbo 与根 README
+
+**Files:**
+
+- Modify: `turbo.json`（根）
+- Modify: `README.md`（根）
+- Create: `apps/docs/README.md`
+
+- [ ] **Step 1: 更新根 `turbo.json` 的 `build.outputs`**
+
+将：
+
+```json
+"outputs": [
+    "dist/**"
+]
+```
+
+改为（与 Next 产物兼容；`!.next/cache/**` 可按需加入以减少缓存体积）：
+
+```json
+"outputs": [
+    "dist/**",
+    ".next/**"
+]
+```
+
+若团队希望排除 `.next/cache`，可使用：
+
+```json
+"outputs": ["dist/**", ".next/**", "!.next/cache/**"]
+```
+
+（以当前 Turbo 版本支持的语法为准。）
+
+- [ ] **Step 2: 根 `README.md`** 在 [Templates](#templates) 表格下增加一行或一小节，例如：
+
+- **文档站**：`apps/docs`（Nextra），本地：`cd apps/docs && pnpm install && pnpm dev` → `http://localhost:3000`；模板应用仍为 `http://localhost:5173`。
+
+- [ ] **Step 3: `apps/docs/README.md`** 重复 dev/build 命令与端口、与 design spec 的链接。
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add turbo.json README.md apps/docs/README.md
+git commit -m "chore: wire docs app into turbo and root README"
+```
+
+---
+
+### Task 8: ESLint（Next 默认）与构建验收
+
+**Files:**
+
+- Create: `apps/docs/eslint.config.mjs`（若 `next lint` 需要；可用 `pnpm exec create-next-app` 生成物参考，或 `eslint.config.mjs` 来自 Next 15 模板）
+- 可选: `apps/docs/.eslintrc.json` — 以 `next lint` 实际生成的为准
+
+- [ ] **Step 1:** 在 `apps/docs` 下运行 `pnpm exec next lint --dir .` 或 `pnpm run lint`，按 CLI 提示补齐缺失配置文件，直到 **0 errors**。
+
+- [ ] **Step 2: 生产构建**
+
+```bash
+cd /Users/zuiidea/web/antd-admin/apps/docs
+pnpm run build
+```
+
+Expected: `next build` 成功退出码 0。
+
+- [ ] **Step 3: 可选搜索** — 按 [Nextra Search 指南](https://nextra.site/docs/guide/search#setup) 配置 Pagefind 或内置搜索；**spec 首期非必须**，可作为 follow-up。
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add apps/docs
+git commit -m "chore(docs): eslint config and verify next build" 
+```
+
+---
+
+## 计划自检（对照 design spec）
+
+| Spec 章节 | 本计划 Task |
+|-----------|-------------|
+| Summary / B 类读者 / 中文 | Task 6 文案与 Task 4 `lang` |
+| Nextra 4 + Docs theme + App Router | Task 2–5 |
+| `apps/docs` workspace | Task 1 |
+| Turbo + README 端口 | Task 7 |
+| `next build` 必须通过 | Task 8 |
+| 首期无 basePath | Task 2 未设置 `basePath`；后续单开任务 |
+| 搜索 / E2E | 未列入（符合 non-goals） |
+
+**占位符：** 无未决 TBD；版本号以 `pnpm install` 后 lockfile 为准在实现时收紧。
+
+---
+
+## 执行方式
+
+**计划路径：** `docs/specs/2026-04-15-apps-docs-nextra-plan.md`
+
+**1. Subagent-Driven（推荐）** — 每 Task 独立子代理 + 任务间 spec/质量审查。  
+**2. Inline Execution** — 本会话按 Task 顺序执行并在 Task 7/8 做检查点。
+
+需要我按其中一种直接开始改仓库时，回复 **1** 或 **2** 即可。