diff --git a/docs/specs/2026-04-15-apps-docs-nextra-plan.md b/docs/specs/2026-04-15-apps-docs-nextra-plan.md index 586a6d2..7b75d9f 100644 --- a/docs/specs/2026-04-15-apps-docs-nextra-plan.md +++ b/docs/specs/2026-04-15-apps-docs-nextra-plan.md @@ -12,24 +12,26 @@ ## 文件映射（新建为主） -| 路径 | 职责 | -|------|------| -| `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` 后更新 | + +| 路径 | 职责 | +| --------------------------------------- | ------------------------------------------------------------------- | +| `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` 后更新 | + --- @@ -39,8 +41,7 @@ - Create: `apps/docs/package.json` - Modify: `pnpm-lock.yaml`（根目录，安装后） - -- [ ] **Step 1: 创建 `apps/docs/package.json`** +- **Step 1: 创建 `apps/docs/package.json`** 内容示例（版本号在安装步骤用 CLI 解析为精确版本并写回 lockfile；此处用 `latest` 或 caret 作为起点）： @@ -74,7 +75,7 @@ } ``` -- [ ] **Step 2: 在仓库根安装** +- **Step 2: 在仓库根安装** ```bash cd /Users/zuiidea/web/antd-admin @@ -83,7 +84,7 @@ pnpm install Expected: 退出码 0，`pnpm-lock.yaml` 更新。 -- [ ] **Step 3: Commit** +- **Step 3: Commit** ```bash git add apps/docs/package.json pnpm-lock.yaml @@ -99,8 +100,7 @@ git commit -m "chore(docs): scaffold antd-admin-docs package with Nextra deps" - 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`** +- **Step 1: 写入 `apps/docs/next.config.mjs`** ```javascript import nextra from "nextra"; @@ -116,7 +116,7 @@ export default withNextra({ （若启用 `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`** +- **Step 2: 写入 `apps/docs/tsconfig.json`** ```json { @@ -142,14 +142,14 @@ export default withNextra({ } ``` -- [ ] **Step 3: 写入 `apps/docs/next-env.d.ts`** +- **Step 3: 写入 `apps/docs/next-env.d.ts`** ```typescript /// /// ``` -- [ ] **Step 4: 验证** +- **Step 4: 验证** ```bash cd apps/docs && pnpm exec tsc --noEmit @@ -157,7 +157,7 @@ cd apps/docs && pnpm exec tsc --noEmit Expected: 在补齐源码文件前可能失败；完成 Task 3–5 后再跑至通过。 -- [ ] **Step 5: Commit** +- **Step 5: Commit** ```bash git add apps/docs/next.config.mjs apps/docs/tsconfig.json apps/docs/next-env.d.ts @@ -171,8 +171,7 @@ git commit -m "chore(docs): add Next and TypeScript config for Nextra" **Files:** - Create: `apps/docs/mdx-components.tsx` - -- [ ] **Step 1: 写入完整文件** +- **Step 1: 写入完整文件** ```tsx import { useMDXComponents as getThemeComponents } from "nextra-theme-docs"; @@ -188,7 +187,7 @@ export function useMDXComponents(components: MDXComponents): MDXComponents { } ``` -- [ ] **Step 2: Commit** +- **Step 2: Commit** ```bash git add apps/docs/mdx-components.tsx @@ -202,8 +201,7 @@ git commit -m "feat(docs): add mdx-components for Nextra theme" **Files:** - Create: `apps/docs/app/layout.tsx` - -- [ ] **Step 1: 写入完整文件**（按需替换 `docsRepositoryBase` 分支名） +- **Step 1: 写入完整文件**（按需替换 `docsRepositoryBase` 分支名） ```tsx import { Footer, Layout, Navbar } from "nextra-theme-docs"; @@ -264,7 +262,7 @@ export default async function RootLayout({ 说明：未加官方示例里的 `Banner`，避免与正式文档抢视觉；若需要公告可后续再加。 -- [ ] **Step 2: Commit** +- **Step 2: Commit** ```bash git add apps/docs/app/layout.tsx @@ -278,8 +276,7 @@ git commit -m "feat(docs): Nextra docs theme root layout (zh-CN)" **Files:** - Create: `apps/docs/app/[[...mdxPath]]/page.tsx` - -- [ ] **Step 1: 写入完整文件**（`mdx-components` 相对路径：从 `app/[[...mdxPath]]/` 到项目根为 `../../`） +- **Step 1: 写入完整文件**（`mdx-components` 相对路径：从 `app/[[...mdxPath]]/` 到项目根为 `../../`） ```tsx import { generateStaticParamsFor, importPage } from "nextra/pages"; @@ -314,7 +311,7 @@ export default async function Page(props: PageProps) { } ``` -- [ ] **Step 2: Commit** +- **Step 2: Commit** ```bash git add "apps/docs/app/[[...mdxPath]]/page.tsx" @@ -332,8 +329,7 @@ git commit -m "feat(docs): add Nextra catch-all MDX page" - Create: `apps/docs/content/templates.mdx` - Create: `apps/docs/content/features.mdx` - Create: `apps/docs/content/configuration.mdx` - -- [ ] **Step 1: 为每个文件添加 frontmatter 与标题**（示例：`index.mdx`） +- **Step 1: 为每个文件添加 frontmatter 与标题**（示例：`index.mdx`） ```mdx --- @@ -346,13 +342,10 @@ 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** +- **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 @@ -368,8 +361,7 @@ git commit -m "docs(docs): add Chinese content skeleton for Nextra" - Modify: `turbo.json`（根） - Modify: `README.md`（根） - Create: `apps/docs/README.md` - -- [ ] **Step 1: 更新根 `turbo.json` 的 `build.outputs`** +- **Step 1: 更新根 `turbo.json` 的 `build.outputs`** 将： @@ -396,13 +388,10 @@ git commit -m "docs(docs): add Chinese content skeleton for Nextra" （以当前 Turbo 版本支持的语法为准。） -- [ ] **Step 2: 根 `README.md`** 在 [Templates](#templates) 表格下增加一行或一小节，例如： - +- **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** +- **Step 3: `apps/docs/README.md`** 重复 dev/build 命令与端口、与 design spec 的链接。 +- **Step 4: Commit** ```bash git add turbo.json README.md apps/docs/README.md @@ -417,10 +406,8 @@ git commit -m "chore: wire docs app into turbo and root README" - 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: 生产构建** +- **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 @@ -429,9 +416,8 @@ 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** +- **Step 3: 可选搜索** — 按 [Nextra Search 指南](https://nextra.site/docs/guide/search#setup) 配置 Pagefind 或内置搜索；**spec 首期非必须**，可作为 follow-up。 +- **Step 4: Commit** ```bash git add apps/docs @@ -442,15 +428,17 @@ 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） | + +| 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 为准在实现时收紧。 @@ -463,4 +451,4 @@ git commit -m "chore(docs): eslint config and verify next build" **1. Subagent-Driven（推荐）** — 每 Task 独立子代理 + 任务间 spec/质量审查。 **2. Inline Execution** — 本会话按 Task 顺序执行并在 Task 7/8 做检查点。 -需要我按其中一种直接开始改仓库时，回复 **1** 或 **2** 即可。 +需要我按其中一种直接开始改仓库时，回复 **1** 或 **2** 即可。 \ No newline at end of file