Alawn/antd-admin
1
0
Fork 0
mirror of https://github.com/zuiidea/antd-admin synced 2026-10-18 05:23:51 +00:00
Code Issues Releases Wiki Activity

docs: update Nextra docs implementation plan

Browse Source 
Made-with: Cursor
This commit is contained in:
zuiidea
2026-04-15 10:01:16 +08:00
parent a54300c588
commit fa163c9456
1 changed files with 59 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/specs/2026-04-15-apps-docs-nextra-plan.md
+59 -71
View File
@@ -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
/// <reference types="next" />
/// <reference types="next/image-types/global" />
```
- [ ] **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** 即可。