diff --git a/apps/docs/README.md b/apps/docs/README.md
index 7d1e7e5..5ec7812 100644
--- a/apps/docs/README.md
+++ b/apps/docs/README.md
@@ -4,31 +4,35 @@
## 内容目录（侧栏分组）
-| 分组 | 路径（`content/` 下） |
-|------|------------------------|
-| 概述 | `index.mdx` |
-| 欢迎 | `welcome/documentation-intro.mdx` |
-| 入门 | `getting-started/`（快速开始、`folder-structure`、`available-scripts` …） |
-| 模板 | `templates/`（模板列表、`basic`、`with-lingui`） |
-| 开发 | `development/` |
-| 样式与资源 | `styles-and-assets/` |
-| 构建应用 | `building/` |
-| 测试 | `testing/` |
-| 后端对接 | `backend/` |
-| 部署 | `deployment/` |
+
+| 分组 | 路径（`content/` 下） |
+| ----- | ----------------------------------------------------------------- |
+| 概述 | `index.mdx` |
+| 欢迎 | `welcome/documentation-intro.mdx` |
+| 入门 | `getting-started/`（快速开始、`folder-structure`、`available-scripts` …） |
+| 模板 | `templates/`（模板列表、`basic`、`with-lingui`） |
+| 开发 | `development/` |
+| 样式与资源 | `styles-and-assets/` |
+| 构建应用 | `building/` |
+| 测试 | `testing/` |
+| 后端对接 | `backend/` |
+| 部署 | `deployment/` |
+
侧边栏顺序与标题由各目录旁 `_meta.js` 及根目录 `content/_meta.js` 配置。
## 端口说明
-| 项目 | 默认开发地址 |
-| ---- | ------------ |
-| 模板应用（`vp dev`） | [http://localhost:5173](http://localhost:5173) |
+
+| 项目 | 默认开发地址 |
+| ---------------- | ---------------------------------------------- |
+| 模板应用（`vp dev`） | [http://localhost:5173](http://localhost:5173) |
| 本文档站（`pnpm dev`） | [http://localhost:3000](http://localhost:3000) |
+
## 常用命令
-在 **`apps/docs`** 目录下：
+在 `**apps/docs**` 目录下：
```bash
pnpm install # 首次或依赖变更后
@@ -46,4 +50,4 @@ cd apps/docs && pnpm install && pnpm dev
## 设计说明
-初始实现见 `docs/specs/2026-04-15-apps-docs-nextra-plan.md`。
+初始实现见 `docs/specs/2026-04-15-apps-docs-nextra-plan.md`。
\ No newline at end of file
diff --git a/apps/docs/app/[[...mdxPath]]/page.tsx b/apps/docs/app/[[...mdxPath]]/page.tsx
deleted file mode 100644
index 78f5067..0000000
--- a/apps/docs/app/[[...mdxPath]]/page.tsx
+++ /dev/null
@@ -1,31 +0,0 @@
-import { generateStaticParamsFor, importPage } from "nextra/pages";
-import { useMDXComponents as getMDXComponents } from "../../mdx-components";
-
-export const generateStaticParams = generateStaticParamsFor("mdxPath");
-
-/** Nextra Docs Theme 在运行时会提供 `wrapper`；类型上可能为 optional。 */
-const Wrapper = getMDXComponents().wrapper!;
-
-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);
-
- return (
-
-
-
- );
-}
diff --git a/apps/docs/app/[lang]/[[...mdxPath]]/page.tsx b/apps/docs/app/[lang]/[[...mdxPath]]/page.tsx
new file mode 100644
index 0000000..3a368c5
--- /dev/null
+++ b/apps/docs/app/[lang]/[[...mdxPath]]/page.tsx
@@ -0,0 +1,33 @@
+import { importPage } from "nextra/pages";
+import type { ReactNode } from "react";
+import { useMDXComponents as getMDXComponents } from "../../../mdx-components";
+
+const Wrapper =
+ getMDXComponents().wrapper ?? ((props: { children?: ReactNode }) => <>{props.children});
+
+type PageProps = { params: Promise<{ lang: string; mdxPath?: string[] }> };
+
+function normalizePath(pathSegments?: string[]) {
+ return (pathSegments ?? []).filter((segment): segment is string => Boolean(segment));
+}
+
+export async function generateMetadata(props: PageProps) {
+ const params = await props.params;
+ const mdxPath = normalizePath(params.mdxPath);
+ const { metadata } = await importPage(mdxPath, params.lang);
+ return metadata;
+}
+
+export default async function Page(props: PageProps) {
+ const params = await props.params;
+ const mdxPath = normalizePath(params.mdxPath);
+ const pageData = await importPage(mdxPath, params.lang);
+ const MDXContent = pageData.default ?? (() => null);
+ const { toc, metadata, sourceCode } = pageData;
+
+ return (
+
+
+
+ );
+}
diff --git a/apps/docs/app/[lang]/layout.tsx b/apps/docs/app/[lang]/layout.tsx
new file mode 100644
index 0000000..5a3e871
--- /dev/null
+++ b/apps/docs/app/[lang]/layout.tsx
@@ -0,0 +1,98 @@
+import { Footer, Layout, Navbar, NotFoundPage } from "nextra-theme-docs";
+import { getPageMap } from "nextra/page-map";
+import "nextra-theme-docs/style.css";
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import type { ReactElement, ReactNode } from "react";
+
+const LOCALES = ["zh", "en"] as const;
+type Locale = (typeof LOCALES)[number];
+
+function isLocale(value: string): value is Locale {
+ return (LOCALES as readonly string[]).includes(value);
+}
+
+function copyFor(locale: Locale) {
+ if (locale === "en") {
+ return {
+ htmlLang: "en",
+ title: "Antd Admin Docs",
+ description:
+ "Antd Admin template guide: choose between basic and with-lingui, then configure and run.",
+ };
+ }
+
+ return {
+ htmlLang: "zh-CN",
+ title: "Antd Admin 文档",
+ description: "antd-admin 模板使用说明：basic 与 with-lingui 选型、安装与配置。",
+ };
+}
+
+export async function generateMetadata({
+ params,
+}: {
+ params: Promise<{ lang: string }>;
+}): Promise {
+ const { lang } = await params;
+ if (!isLocale(lang)) return {};
+ const copy = copyFor(lang);
+
+ return {
+ title: {
+ default: copy.title,
+ template: `%s – ${copy.title}`,
+ },
+ description: copy.description,
+ };
+}
+
+export default async function RootLayout({
+ children,
+ params,
+}: {
+ children: ReactNode;
+ params: Promise<{ lang: string }>;
+}): Promise {
+ const { lang } = await params;
+ if (!isLocale(lang)) notFound();
+
+ const copy = copyFor(lang);
+ const localizedPageMap = await getPageMap(`/${lang}`);
+ const pageMap = (Array.isArray(localizedPageMap) ? localizedPageMap : []).filter(Boolean);
+
+ return (
+
+
+ {copy.title}}
+ projectLink="https://github.com/zuiidea/antd-admin"
+ />
+ }
+ pageMap={pageMap}
+ docsRepositoryBase="https://github.com/zuiidea/antd-admin/tree/master"
+ i18n={[
+ { locale: "zh", name: "中文" },
+ { locale: "en", name: "English" },
+ ]}
+ footer={
+
+ }
+ >
+ {children}
+
+
+
+ );
+}
+
+export function NotFound() {
+ return ;
+}
diff --git a/apps/docs/app/[lang]/not-found.tsx b/apps/docs/app/[lang]/not-found.tsx
new file mode 100644
index 0000000..d1f92d9
--- /dev/null
+++ b/apps/docs/app/[lang]/not-found.tsx
@@ -0,0 +1,5 @@
+import { NotFoundPage } from "nextra-theme-docs";
+
+export default function NotFound() {
+ return ;
+}
diff --git a/apps/docs/app/layout.tsx b/apps/docs/app/layout.tsx
deleted file mode 100644
index d9dac0d..0000000
--- a/apps/docs/app/layout.tsx
+++ /dev/null
@@ -1,54 +0,0 @@
-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 = (
- Antd Admin 文档}
- projectLink="https://github.com/zuiidea/antd-admin"
- />
-);
-
-const footer = (
-
-);
-
-export default async function RootLayout({
- children,
-}: {
- children: ReactNode;
-}): Promise {
- const pageMap = await getPageMap();
-
- return (
-
-
-
-
- {children}
-
-
-
- );
-}
diff --git a/apps/docs/content/en/_meta.js b/apps/docs/content/en/_meta.js
new file mode 100644
index 0000000..05f7cd0
--- /dev/null
+++ b/apps/docs/content/en/_meta.js
@@ -0,0 +1,13 @@
+/** @type {import('nextra').MetaRecord} */
+export default {
+ index: "Overview",
+ welcome: "Welcome",
+ "getting-started": "Getting Started",
+ templates: "Templates",
+ development: "Development",
+ "styles-and-assets": "Styles & Assets",
+ building: "Building",
+ testing: "Testing",
+ backend: "Backend Integration",
+ deployment: "Deployment",
+};
diff --git a/apps/docs/content/en/backend/_meta.js b/apps/docs/content/en/backend/_meta.js
new file mode 100644
index 0000000..7e1fa84
--- /dev/null
+++ b/apps/docs/content/en/backend/_meta.js
@@ -0,0 +1,4 @@
+/** @type {import('nextra').MetaRecord} */
+export default {
+ "proxying-api-requests": "Proxying API Requests",
+};
diff --git a/apps/docs/content/en/backend/proxying-api-requests.mdx b/apps/docs/content/en/backend/proxying-api-requests.mdx
new file mode 100644
index 0000000..4adfbd7
--- /dev/null
+++ b/apps/docs/content/en/backend/proxying-api-requests.mdx
@@ -0,0 +1,14 @@
+---
+title: Proxying API Requests
+description: Configure API proxying between frontend and backend
+---
+
+# Proxying API Requests
+
+Use a proxy layer in development to avoid CORS issues and keep API endpoints configurable.
+
+Recommended approach:
+
+- Define a consistent API prefix.
+- Route requests by environment.
+- Keep backend base URLs in environment variables.
diff --git a/apps/docs/content/en/building/_meta.js b/apps/docs/content/en/building/_meta.js
new file mode 100644
index 0000000..0081230
--- /dev/null
+++ b/apps/docs/content/en/building/_meta.js
@@ -0,0 +1,7 @@
+/** @type {import('nextra').MetaRecord} */
+export default {
+ "environment-variables": "Environment Variables",
+ performance: "Performance",
+ "production-build": "Production Build",
+ router: "Router",
+};
diff --git a/apps/docs/content/en/building/environment-variables.mdx b/apps/docs/content/en/building/environment-variables.mdx
new file mode 100644
index 0000000..a2899aa
--- /dev/null
+++ b/apps/docs/content/en/building/environment-variables.mdx
@@ -0,0 +1,12 @@
+---
+title: Environment Variables
+description: Manage environment configuration safely across environments
+---
+
+# Environment Variables
+
+Use environment variables to separate configuration from code.
+
+- Keep secrets out of source files.
+- Use environment-specific values for dev/staging/prod.
+- Document required variables for contributors.
diff --git a/apps/docs/content/en/building/performance.mdx b/apps/docs/content/en/building/performance.mdx
new file mode 100644
index 0000000..271b35d
--- /dev/null
+++ b/apps/docs/content/en/building/performance.mdx
@@ -0,0 +1,13 @@
+---
+title: Performance
+description: Practical optimization checklist for admin applications
+---
+
+# Performance
+
+Focus on practical wins:
+
+- Reduce unnecessary rerenders
+- Split heavy modules
+- Cache requests where appropriate
+- Measure before and after each optimization
diff --git a/apps/docs/content/en/building/production-build.mdx b/apps/docs/content/en/building/production-build.mdx
new file mode 100644
index 0000000..b4fb791
--- /dev/null
+++ b/apps/docs/content/en/building/production-build.mdx
@@ -0,0 +1,19 @@
+---
+title: Production Build
+description: Build and validate for production deployment
+---
+
+# Production Build
+
+Before deployment:
+
+1. Run production build.
+2. Verify lint and tests.
+3. Validate key user flows in preview/staging.
+
+Example:
+
+```bash
+pnpm --filter ./apps/basic build
+pnpm --filter ./apps/with-lingui build
+```
diff --git a/apps/docs/content/en/building/router.mdx b/apps/docs/content/en/building/router.mdx
new file mode 100644
index 0000000..2dd3fb4
--- /dev/null
+++ b/apps/docs/content/en/building/router.mdx
@@ -0,0 +1,14 @@
+---
+title: Router
+description: Routing conventions and recommendations
+---
+
+# Router
+
+Use clear route grouping and layout boundaries.
+
+Recommendations:
+
+- Keep feature routes close to feature modules
+- Avoid deeply coupled route dependencies
+- Handle auth/permission checks in a predictable layer
diff --git a/apps/docs/content/en/deployment/index.mdx b/apps/docs/content/en/deployment/index.mdx
new file mode 100644
index 0000000..31b154d
--- /dev/null
+++ b/apps/docs/content/en/deployment/index.mdx
@@ -0,0 +1,15 @@
+---
+title: Deployment
+description: Deployment guidance and rollout checklist
+---
+
+# Deployment
+
+Before production rollout:
+
+- Validate environment variables
+- Run full build and tests
+- Verify critical user journeys
+- Set up monitoring and error tracking
+
+Deploy progressively when possible and prepare a rollback plan.
diff --git a/apps/docs/content/en/development/_meta.js b/apps/docs/content/en/development/_meta.js
new file mode 100644
index 0000000..9984de0
--- /dev/null
+++ b/apps/docs/content/en/development/_meta.js
@@ -0,0 +1,5 @@
+/** @type {import('nextra').MetaRecord} */
+export default {
+ "bundle-analysis": "Bundle Analysis",
+ "https-in-development": "HTTPS in Development",
+};
diff --git a/apps/docs/content/en/development/bundle-analysis.mdx b/apps/docs/content/en/development/bundle-analysis.mdx
new file mode 100644
index 0000000..f4bd72d
--- /dev/null
+++ b/apps/docs/content/en/development/bundle-analysis.mdx
@@ -0,0 +1,16 @@
+---
+title: Bundle Analysis
+description: Analyze bundle size and optimize package usage
+---
+
+# Bundle Analysis
+
+Use your build tooling and analyzer plugins to inspect bundle composition.
+
+Focus on:
+
+- Heavy dependencies
+- Duplicate packages
+- Over-imported UI modules
+
+After optimization, rerun build and compare the output artifacts.
diff --git a/apps/docs/content/en/development/https-in-development.mdx b/apps/docs/content/en/development/https-in-development.mdx
new file mode 100644
index 0000000..becb67b
--- /dev/null
+++ b/apps/docs/content/en/development/https-in-development.mdx
@@ -0,0 +1,10 @@
+---
+title: HTTPS in Development
+description: Enable HTTPS for local development when needed
+---
+
+# HTTPS in Development
+
+If your scenario requires secure context (for example some browser APIs), enable HTTPS in local dev by configuring your dev server certificates.
+
+Keep certificates out of version control and share setup instructions with your team.
diff --git a/apps/docs/content/en/getting-started/_meta.js b/apps/docs/content/en/getting-started/_meta.js
new file mode 100644
index 0000000..cd6fa60
--- /dev/null
+++ b/apps/docs/content/en/getting-started/_meta.js
@@ -0,0 +1,9 @@
+/** @type {import('nextra').MetaRecord} */
+export default {
+ index: "Getting Started",
+ "available-scripts": "Available Scripts",
+ "folder-structure": "Folder Structure",
+ "supported-browsers": "Supported Browsers",
+ "supported-features": "Supported Features",
+ "updating-releases": "Updating Releases",
+};
diff --git a/apps/docs/content/en/getting-started/available-scripts.mdx b/apps/docs/content/en/getting-started/available-scripts.mdx
new file mode 100644
index 0000000..f7bd4f8
--- /dev/null
+++ b/apps/docs/content/en/getting-started/available-scripts.mdx
@@ -0,0 +1,44 @@
+---
+title: Available Scripts
+description: Common pnpm scripts and usage in this monorepo
+---
+
+# Available Scripts
+
+## Workspace-Level
+
+```bash
+pnpm install
+pnpm -r build
+pnpm -r lint
+pnpm -r test
+```
+
+## docs (`apps/docs`)
+
+```bash
+pnpm --filter ./apps/docs dev
+pnpm --filter ./apps/docs build
+pnpm --filter ./apps/docs start
+```
+
+## basic (`apps/basic`)
+
+```bash
+pnpm --filter ./apps/basic dev
+pnpm --filter ./apps/basic build
+pnpm --filter ./apps/basic preview
+```
+
+## with-lingui (`apps/with-lingui`)
+
+```bash
+pnpm --filter ./apps/with-lingui dev
+pnpm --filter ./apps/with-lingui build
+pnpm --filter ./apps/with-lingui preview
+```
+
+## Notes
+
+- Use `--filter` to scope commands to a single app.
+- Run commands at the repository root for consistent workspace behavior.
diff --git a/apps/docs/content/en/getting-started/folder-structure.mdx b/apps/docs/content/en/getting-started/folder-structure.mdx
new file mode 100644
index 0000000..29759da
--- /dev/null
+++ b/apps/docs/content/en/getting-started/folder-structure.mdx
@@ -0,0 +1,28 @@
+---
+title: Folder Structure
+description: Key directories and responsibilities in the repository
+---
+
+# Folder Structure
+
+```text
+.
+├─ apps/
+│ ├─ basic/
+│ ├─ with-lingui/
+│ └─ docs/
+├─ packages/
+├─ pnpm-workspace.yaml
+└─ turbo.json
+```
+
+## Directory Guide
+
+- `apps/basic`: Main admin template (English)
+- `apps/with-lingui`: Admin template with Lingui i18n
+- `apps/docs`: Documentation site (Nextra + Next.js)
+- `packages`: Shared packages and utilities
+
+## Recommendation
+
+When creating reusable logic, prioritize placing it in `packages` rather than duplicating in app folders.
diff --git a/apps/docs/content/en/getting-started/index.mdx b/apps/docs/content/en/getting-started/index.mdx
new file mode 100644
index 0000000..a538d4f
--- /dev/null
+++ b/apps/docs/content/en/getting-started/index.mdx
@@ -0,0 +1,43 @@
+---
+title: Getting Started
+description: Install dependencies, start development, and build applications
+---
+
+# Getting Started
+
+## Requirements
+
+- Node.js 20+
+- pnpm 9+
+
+## Install Dependencies
+
+```bash
+pnpm install
+```
+
+## Run Projects
+
+```bash
+# Run docs
+pnpm --filter ./apps/docs dev
+
+# Run basic template
+pnpm --filter ./apps/basic dev
+
+# Run Lingui template
+pnpm --filter ./apps/with-lingui dev
+```
+
+## Build
+
+```bash
+pnpm --filter ./apps/basic build
+pnpm --filter ./apps/with-lingui build
+```
+
+## Next Steps
+
+- Scripts: [Available Scripts](/en/getting-started/available-scripts)
+- Structure: [Folder Structure](/en/getting-started/folder-structure)
+- Browser support: [Supported Browsers](/en/getting-started/supported-browsers)
diff --git a/apps/docs/content/en/getting-started/supported-browsers.mdx b/apps/docs/content/en/getting-started/supported-browsers.mdx
new file mode 100644
index 0000000..f4bb961
--- /dev/null
+++ b/apps/docs/content/en/getting-started/supported-browsers.mdx
@@ -0,0 +1,15 @@
+---
+title: Supported Browsers
+description: Browser compatibility policy for this project
+---
+
+# Supported Browsers
+
+This project targets modern evergreen browsers:
+
+- Latest Chrome
+- Latest Edge
+- Latest Firefox
+- Latest Safari
+
+For old browser support requirements, evaluate and add polyfills case-by-case based on your user base.
diff --git a/apps/docs/content/en/getting-started/supported-features.mdx b/apps/docs/content/en/getting-started/supported-features.mdx
new file mode 100644
index 0000000..4932b6a
--- /dev/null
+++ b/apps/docs/content/en/getting-started/supported-features.mdx
@@ -0,0 +1,17 @@
+---
+title: Supported Features
+description: Core features available in the templates
+---
+
+# Supported Features
+
+The templates include:
+
+- User login and permission-based routing
+- Dashboard and reusable business pages
+- Request abstraction and API proxy support
+- Theme and layout customization
+- Mock data support with MSW
+- Unit tests and E2E tests
+
+Feature details may vary slightly between `basic` and `with-lingui`.
diff --git a/apps/docs/content/en/getting-started/updating-releases.mdx b/apps/docs/content/en/getting-started/updating-releases.mdx
new file mode 100644
index 0000000..efb4cc9
--- /dev/null
+++ b/apps/docs/content/en/getting-started/updating-releases.mdx
@@ -0,0 +1,15 @@
+---
+title: Updating Releases
+description: Recommendations for keeping your project up to date
+---
+
+# Updating Releases
+
+To keep your project updated:
+
+1. Pull the latest code from upstream.
+2. Run `pnpm install` to refresh lockfile-resolved dependencies.
+3. Verify with `build`, `lint`, and `test`.
+4. Resolve breaking changes before releasing.
+
+For production apps, perform updates on a branch and validate in CI before merging.
diff --git a/apps/docs/content/en/index.mdx b/apps/docs/content/en/index.mdx
new file mode 100644
index 0000000..b0f472c
--- /dev/null
+++ b/apps/docs/content/en/index.mdx
@@ -0,0 +1,16 @@
+---
+title: Overview
+description: antd-admin monorepo and docs guide
+---
+
+# Overview
+
+This repository provides two runnable admin templates: **[`apps/basic`](https://github.com/zuiidea/antd-admin/tree/master/apps/basic)** (English UI) and **[`apps/with-lingui`](https://github.com/zuiidea/antd-admin/tree/master/apps/with-lingui)** (Lingui-based bilingual UI).
+
+The stack centers on **React 19, Ant Design 6, TanStack Router & Query, Vite+ (`vp`), MSW, and Playwright**.
+
+The sidebar is organized as: Welcome → Getting Started → Templates → Development → Styles & Assets → Building → Testing → Backend Integration → Deployment.
+
+Start from **[Getting Started](/en/getting-started)**, then choose a template in **[Templates](/en/templates)**.
+
+GitHub: [zuiidea/antd-admin](https://github.com/zuiidea/antd-admin)
diff --git a/apps/docs/content/en/styles-and-assets/_meta.js b/apps/docs/content/en/styles-and-assets/_meta.js
new file mode 100644
index 0000000..911854f
--- /dev/null
+++ b/apps/docs/content/en/styles-and-assets/_meta.js
@@ -0,0 +1,8 @@
+/** @type {import('nextra').MetaRecord} */
+export default {
+ "code-splitting": "Code Splitting",
+ "css-modules": "CSS Modules",
+ "images-fonts-files": "Images, Fonts, and Files",
+ "public-folder": "Public Folder",
+ stylesheet: "Stylesheet",
+};
diff --git a/apps/docs/content/en/styles-and-assets/code-splitting.mdx b/apps/docs/content/en/styles-and-assets/code-splitting.mdx
new file mode 100644
index 0000000..cb4a099
--- /dev/null
+++ b/apps/docs/content/en/styles-and-assets/code-splitting.mdx
@@ -0,0 +1,10 @@
+---
+title: Code Splitting
+description: Reduce initial payload with route-level and module-level splitting
+---
+
+# Code Splitting
+
+Apply code splitting for large routes and rarely used modules to improve first-load performance.
+
+Use dynamic imports where appropriate and avoid loading heavy modules on initial render.
diff --git a/apps/docs/content/en/styles-and-assets/css-modules.mdx b/apps/docs/content/en/styles-and-assets/css-modules.mdx
new file mode 100644
index 0000000..2882e29
--- /dev/null
+++ b/apps/docs/content/en/styles-and-assets/css-modules.mdx
@@ -0,0 +1,10 @@
+---
+title: CSS Modules
+description: Scoped styling strategy in the project
+---
+
+# CSS Modules
+
+Use CSS Modules for component-scoped styles to reduce global style conflicts.
+
+Adopt clear naming and keep styles colocated with the related component.
diff --git a/apps/docs/content/en/styles-and-assets/images-fonts-files.mdx b/apps/docs/content/en/styles-and-assets/images-fonts-files.mdx
new file mode 100644
index 0000000..21a627d
--- /dev/null
+++ b/apps/docs/content/en/styles-and-assets/images-fonts-files.mdx
@@ -0,0 +1,10 @@
+---
+title: Images, Fonts, and Files
+description: Best practices for static asset management
+---
+
+# Images, Fonts, and Files
+
+Place static assets in predictable directories and reference them consistently.
+
+For large files, consider CDN delivery and caching strategy to improve load performance.
diff --git a/apps/docs/content/en/styles-and-assets/public-folder.mdx b/apps/docs/content/en/styles-and-assets/public-folder.mdx
new file mode 100644
index 0000000..71c8e0e
--- /dev/null
+++ b/apps/docs/content/en/styles-and-assets/public-folder.mdx
@@ -0,0 +1,10 @@
+---
+title: Public Folder
+description: How to use public assets in apps
+---
+
+# Public Folder
+
+Use the public folder for static files that should be served directly.
+
+Keep naming stable and avoid storing sensitive content in public assets.
diff --git a/apps/docs/content/en/styles-and-assets/stylesheet.mdx b/apps/docs/content/en/styles-and-assets/stylesheet.mdx
new file mode 100644
index 0000000..3b04c24
--- /dev/null
+++ b/apps/docs/content/en/styles-and-assets/stylesheet.mdx
@@ -0,0 +1,13 @@
+---
+title: Stylesheet
+description: Organize global and component styles clearly
+---
+
+# Stylesheet
+
+Keep a clear separation between:
+
+- Global style tokens and resets
+- Component-local styles
+
+This helps maintain consistency and avoids accidental style leakage.
diff --git a/apps/docs/content/en/templates/_meta.js b/apps/docs/content/en/templates/_meta.js
new file mode 100644
index 0000000..5823be0
--- /dev/null
+++ b/apps/docs/content/en/templates/_meta.js
@@ -0,0 +1,6 @@
+/** @type {import('nextra').MetaRecord} */
+export default {
+ index: "Templates",
+ basic: "basic",
+ "with-lingui": "with-lingui",
+};
diff --git a/apps/docs/content/en/templates/basic.mdx b/apps/docs/content/en/templates/basic.mdx
new file mode 100644
index 0000000..09b47e7
--- /dev/null
+++ b/apps/docs/content/en/templates/basic.mdx
@@ -0,0 +1,26 @@
+---
+title: basic
+description: Lightweight admin template for single-language projects
+---
+
+# basic
+
+`apps/basic` is a streamlined admin template focused on fast startup and simple extension.
+
+## Good Fit
+
+- Internal tools
+- Small-to-medium dashboard projects
+- Teams not requiring i18n yet
+
+## Highlights
+
+- Clean route organization
+- Common data table and form patterns
+- Practical defaults for request handling and page layout
+
+## Start Development
+
+```bash
+pnpm --filter ./apps/basic dev
+```
diff --git a/apps/docs/content/en/templates/index.mdx b/apps/docs/content/en/templates/index.mdx
new file mode 100644
index 0000000..5080f40
--- /dev/null
+++ b/apps/docs/content/en/templates/index.mdx
@@ -0,0 +1,16 @@
+---
+title: Templates
+description: Choose between basic and with-lingui templates
+---
+
+# Templates
+
+This repository provides two templates:
+
+- **[basic](/en/templates/basic)**: Minimal setup, English UI by default.
+- **[with-lingui](/en/templates/with-lingui)**: Includes Lingui i18n workflow and bilingual setup.
+
+## How to Choose
+
+- Choose **basic** if you only need one language.
+- Choose **with-lingui** if you need structured multilingual support from day one.
diff --git a/apps/docs/content/en/templates/with-lingui.mdx b/apps/docs/content/en/templates/with-lingui.mdx
new file mode 100644
index 0000000..3520acd
--- /dev/null
+++ b/apps/docs/content/en/templates/with-lingui.mdx
@@ -0,0 +1,26 @@
+---
+title: with-lingui
+description: Admin template with Lingui internationalization
+---
+
+# with-lingui
+
+`apps/with-lingui` adds multilingual capabilities based on Lingui while keeping the same admin architecture.
+
+## Good Fit
+
+- Products serving multiple regions/languages
+- Teams that want standardized translation workflow
+- Projects requiring language switch in UI
+
+## Highlights
+
+- Lingui message extraction and compilation flow
+- Language resource organization
+- Built-in language switching patterns
+
+## Start Development
+
+```bash
+pnpm --filter ./apps/with-lingui dev
+```
diff --git a/apps/docs/content/en/testing/_meta.js b/apps/docs/content/en/testing/_meta.js
new file mode 100644
index 0000000..2e7c508
--- /dev/null
+++ b/apps/docs/content/en/testing/_meta.js
@@ -0,0 +1,5 @@
+/** @type {import('nextra').MetaRecord} */
+export default {
+ "running-tests": "Running Tests",
+ "debugging-tests": "Debugging Tests",
+};
diff --git a/apps/docs/content/en/testing/debugging-tests.mdx b/apps/docs/content/en/testing/debugging-tests.mdx
new file mode 100644
index 0000000..7e67ae4
--- /dev/null
+++ b/apps/docs/content/en/testing/debugging-tests.mdx
@@ -0,0 +1,15 @@
+---
+title: Debugging Tests
+description: Diagnose flaky or failing tests effectively
+---
+
+# Debugging Tests
+
+When tests fail:
+
+1. Reproduce locally with focused scope.
+2. Inspect stack traces and assertions.
+3. Isolate flaky dependencies (time, network, global state).
+4. Stabilize with proper setup/teardown.
+
+Prefer fixing root causes over adding retries.
diff --git a/apps/docs/content/en/testing/running-tests.mdx b/apps/docs/content/en/testing/running-tests.mdx
new file mode 100644
index 0000000..91ae2c3
--- /dev/null
+++ b/apps/docs/content/en/testing/running-tests.mdx
@@ -0,0 +1,18 @@
+---
+title: Running Tests
+description: Run unit and e2e tests in this repository
+---
+
+# Running Tests
+
+Run tests from repository root or per app.
+
+Common commands:
+
+```bash
+pnpm -r test
+pnpm --filter ./apps/basic test
+pnpm --filter ./apps/with-lingui test
+```
+
+Set up CI to run tests on pull requests before merge.
diff --git a/apps/docs/content/en/welcome/_meta.js b/apps/docs/content/en/welcome/_meta.js
new file mode 100644
index 0000000..f52999f
--- /dev/null
+++ b/apps/docs/content/en/welcome/_meta.js
@@ -0,0 +1,4 @@
+/** @type {import('nextra').MetaRecord} */
+export default {
+ "documentation-intro": "Documentation Overview",
+};
diff --git a/apps/docs/content/en/welcome/documentation-intro.mdx b/apps/docs/content/en/welcome/documentation-intro.mdx
new file mode 100644
index 0000000..6048ab5
--- /dev/null
+++ b/apps/docs/content/en/welcome/documentation-intro.mdx
@@ -0,0 +1,24 @@
+---
+title: Documentation Overview
+description: How to use this documentation and choose a project template
+---
+
+# Documentation Overview
+
+The docs in this project are built with **Nextra + Next.js App Router**.
+
+If this is your first time here:
+
+1. Read **[Getting Started](/en/getting-started)** for setup and scripts.
+2. Compare templates in **[Templates](/en/templates)**.
+3. Go to **[Backend Integration](/en/backend/proxying-api-requests)** if you need API setup.
+
+## Repo Structure
+
+- `apps/basic`: English-only admin template
+- `apps/with-lingui`: Internationalized template with Lingui
+- `apps/docs`: Documentation site
+
+## Recommended Reading Order
+
+Welcome → Getting Started → Templates → Development → Building → Testing → Deployment
diff --git a/apps/docs/content/_meta.js b/apps/docs/content/zh/_meta.js
similarity index 100%
rename from apps/docs/content/_meta.js
rename to apps/docs/content/zh/_meta.js
diff --git a/apps/docs/content/backend/_meta.js b/apps/docs/content/zh/backend/_meta.js
similarity index 100%
rename from apps/docs/content/backend/_meta.js
rename to apps/docs/content/zh/backend/_meta.js
diff --git a/apps/docs/content/backend/proxying-api-requests.mdx b/apps/docs/content/zh/backend/proxying-api-requests.mdx
similarity index 100%
rename from apps/docs/content/backend/proxying-api-requests.mdx
rename to apps/docs/content/zh/backend/proxying-api-requests.mdx
diff --git a/apps/docs/content/building/_meta.js b/apps/docs/content/zh/building/_meta.js
similarity index 100%
rename from apps/docs/content/building/_meta.js
rename to apps/docs/content/zh/building/_meta.js
diff --git a/apps/docs/content/building/environment-variables.mdx b/apps/docs/content/zh/building/environment-variables.mdx
similarity index 100%
rename from apps/docs/content/building/environment-variables.mdx
rename to apps/docs/content/zh/building/environment-variables.mdx
diff --git a/apps/docs/content/building/performance.mdx b/apps/docs/content/zh/building/performance.mdx
similarity index 100%
rename from apps/docs/content/building/performance.mdx
rename to apps/docs/content/zh/building/performance.mdx
diff --git a/apps/docs/content/building/production-build.mdx b/apps/docs/content/zh/building/production-build.mdx
similarity index 100%
rename from apps/docs/content/building/production-build.mdx
rename to apps/docs/content/zh/building/production-build.mdx
diff --git a/apps/docs/content/building/router.mdx b/apps/docs/content/zh/building/router.mdx
similarity index 100%
rename from apps/docs/content/building/router.mdx
rename to apps/docs/content/zh/building/router.mdx
diff --git a/apps/docs/content/deployment/index.mdx b/apps/docs/content/zh/deployment/index.mdx
similarity index 100%
rename from apps/docs/content/deployment/index.mdx
rename to apps/docs/content/zh/deployment/index.mdx
diff --git a/apps/docs/content/development/_meta.js b/apps/docs/content/zh/development/_meta.js
similarity index 100%
rename from apps/docs/content/development/_meta.js
rename to apps/docs/content/zh/development/_meta.js
diff --git a/apps/docs/content/development/bundle-analysis.mdx b/apps/docs/content/zh/development/bundle-analysis.mdx
similarity index 100%
rename from apps/docs/content/development/bundle-analysis.mdx
rename to apps/docs/content/zh/development/bundle-analysis.mdx
diff --git a/apps/docs/content/development/https-in-development.mdx b/apps/docs/content/zh/development/https-in-development.mdx
similarity index 100%
rename from apps/docs/content/development/https-in-development.mdx
rename to apps/docs/content/zh/development/https-in-development.mdx
diff --git a/apps/docs/content/getting-started/_meta.js b/apps/docs/content/zh/getting-started/_meta.js
similarity index 100%
rename from apps/docs/content/getting-started/_meta.js
rename to apps/docs/content/zh/getting-started/_meta.js
diff --git a/apps/docs/content/getting-started/available-scripts.mdx b/apps/docs/content/zh/getting-started/available-scripts.mdx
similarity index 100%
rename from apps/docs/content/getting-started/available-scripts.mdx
rename to apps/docs/content/zh/getting-started/available-scripts.mdx
diff --git a/apps/docs/content/getting-started/folder-structure.mdx b/apps/docs/content/zh/getting-started/folder-structure.mdx
similarity index 100%
rename from apps/docs/content/getting-started/folder-structure.mdx
rename to apps/docs/content/zh/getting-started/folder-structure.mdx
diff --git a/apps/docs/content/getting-started/index.mdx b/apps/docs/content/zh/getting-started/index.mdx
similarity index 100%
rename from apps/docs/content/getting-started/index.mdx
rename to apps/docs/content/zh/getting-started/index.mdx
diff --git a/apps/docs/content/getting-started/supported-browsers.mdx b/apps/docs/content/zh/getting-started/supported-browsers.mdx
similarity index 100%
rename from apps/docs/content/getting-started/supported-browsers.mdx
rename to apps/docs/content/zh/getting-started/supported-browsers.mdx
diff --git a/apps/docs/content/getting-started/supported-features.mdx b/apps/docs/content/zh/getting-started/supported-features.mdx
similarity index 100%
rename from apps/docs/content/getting-started/supported-features.mdx
rename to apps/docs/content/zh/getting-started/supported-features.mdx
diff --git a/apps/docs/content/getting-started/updating-releases.mdx b/apps/docs/content/zh/getting-started/updating-releases.mdx
similarity index 100%
rename from apps/docs/content/getting-started/updating-releases.mdx
rename to apps/docs/content/zh/getting-started/updating-releases.mdx
diff --git a/apps/docs/content/index.mdx b/apps/docs/content/zh/index.mdx
similarity index 100%
rename from apps/docs/content/index.mdx
rename to apps/docs/content/zh/index.mdx
diff --git a/apps/docs/content/styles-and-assets/_meta.js b/apps/docs/content/zh/styles-and-assets/_meta.js
similarity index 100%
rename from apps/docs/content/styles-and-assets/_meta.js
rename to apps/docs/content/zh/styles-and-assets/_meta.js
diff --git a/apps/docs/content/styles-and-assets/code-splitting.mdx b/apps/docs/content/zh/styles-and-assets/code-splitting.mdx
similarity index 100%
rename from apps/docs/content/styles-and-assets/code-splitting.mdx
rename to apps/docs/content/zh/styles-and-assets/code-splitting.mdx
diff --git a/apps/docs/content/styles-and-assets/css-modules.mdx b/apps/docs/content/zh/styles-and-assets/css-modules.mdx
similarity index 100%
rename from apps/docs/content/styles-and-assets/css-modules.mdx
rename to apps/docs/content/zh/styles-and-assets/css-modules.mdx
diff --git a/apps/docs/content/styles-and-assets/images-fonts-files.mdx b/apps/docs/content/zh/styles-and-assets/images-fonts-files.mdx
similarity index 100%
rename from apps/docs/content/styles-and-assets/images-fonts-files.mdx
rename to apps/docs/content/zh/styles-and-assets/images-fonts-files.mdx
diff --git a/apps/docs/content/styles-and-assets/public-folder.mdx b/apps/docs/content/zh/styles-and-assets/public-folder.mdx
similarity index 100%
rename from apps/docs/content/styles-and-assets/public-folder.mdx
rename to apps/docs/content/zh/styles-and-assets/public-folder.mdx
diff --git a/apps/docs/content/styles-and-assets/stylesheet.mdx b/apps/docs/content/zh/styles-and-assets/stylesheet.mdx
similarity index 100%
rename from apps/docs/content/styles-and-assets/stylesheet.mdx
rename to apps/docs/content/zh/styles-and-assets/stylesheet.mdx
diff --git a/apps/docs/content/templates/_meta.js b/apps/docs/content/zh/templates/_meta.js
similarity index 100%
rename from apps/docs/content/templates/_meta.js
rename to apps/docs/content/zh/templates/_meta.js
diff --git a/apps/docs/content/templates/basic.mdx b/apps/docs/content/zh/templates/basic.mdx
similarity index 100%
rename from apps/docs/content/templates/basic.mdx
rename to apps/docs/content/zh/templates/basic.mdx
diff --git a/apps/docs/content/templates/index.mdx b/apps/docs/content/zh/templates/index.mdx
similarity index 100%
rename from apps/docs/content/templates/index.mdx
rename to apps/docs/content/zh/templates/index.mdx
diff --git a/apps/docs/content/templates/with-lingui.mdx b/apps/docs/content/zh/templates/with-lingui.mdx
similarity index 100%
rename from apps/docs/content/templates/with-lingui.mdx
rename to apps/docs/content/zh/templates/with-lingui.mdx
diff --git a/apps/docs/content/testing/_meta.js b/apps/docs/content/zh/testing/_meta.js
similarity index 100%
rename from apps/docs/content/testing/_meta.js
rename to apps/docs/content/zh/testing/_meta.js
diff --git a/apps/docs/content/testing/debugging-tests.mdx b/apps/docs/content/zh/testing/debugging-tests.mdx
similarity index 100%
rename from apps/docs/content/testing/debugging-tests.mdx
rename to apps/docs/content/zh/testing/debugging-tests.mdx
diff --git a/apps/docs/content/testing/running-tests.mdx b/apps/docs/content/zh/testing/running-tests.mdx
similarity index 100%
rename from apps/docs/content/testing/running-tests.mdx
rename to apps/docs/content/zh/testing/running-tests.mdx
diff --git a/apps/docs/content/welcome/_meta.js b/apps/docs/content/zh/welcome/_meta.js
similarity index 100%
rename from apps/docs/content/welcome/_meta.js
rename to apps/docs/content/zh/welcome/_meta.js
diff --git a/apps/docs/content/welcome/documentation-intro.mdx b/apps/docs/content/zh/welcome/documentation-intro.mdx
similarity index 100%
rename from apps/docs/content/welcome/documentation-intro.mdx
rename to apps/docs/content/zh/welcome/documentation-intro.mdx
diff --git a/apps/docs/eslint.config.mjs b/apps/docs/eslint.config.mjs
index 5ae1806..2c03022 100644
--- a/apps/docs/eslint.config.mjs
+++ b/apps/docs/eslint.config.mjs
@@ -14,7 +14,6 @@ export default [
{
files: ["mdx-components.tsx"],
rules: {
- // Nextra 主题在模块顶层合并默认 MDX 组件；与 `use*` 命名冲突于 hooks 规则，见 https://nextra.site/docs/file-conventions/mdx-components-file
"react-hooks/rules-of-hooks": "off",
},
},
diff --git a/apps/docs/next-env.d.ts b/apps/docs/next-env.d.ts
index c4b7818..9edff1c 100644
--- a/apps/docs/next-env.d.ts
+++ b/apps/docs/next-env.d.ts
@@ -1,6 +1,6 @@
///
///
-import "./.next/dev/types/routes.d.ts";
+import "./.next/types/routes.d.ts";
// NOTE: This file should not be edited
// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
diff --git a/apps/docs/next.config.mjs b/apps/docs/next.config.mjs
index 6b6cf14..bdbfa4e 100644
--- a/apps/docs/next.config.mjs
+++ b/apps/docs/next.config.mjs
@@ -6,4 +6,8 @@ const withNextra = nextra({
export default withNextra({
reactStrictMode: true,
+ i18n: {
+ locales: ["zh", "en"],
+ defaultLocale: "zh",
+ },
});
diff --git a/apps/docs/package.json b/apps/docs/package.json
index f37b8e5..b1576c9 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -6,7 +6,7 @@
"dev": "next dev -p 3003",
"build": "next build",
"start": "next start -p 3000",
- "lint": "next lint"
+ "lint": "tsc --noEmit"
},
"dependencies": {
"next": "^16.2.4",
diff --git a/apps/docs/proxy.ts b/apps/docs/proxy.ts
index c5088b8..38bc43b 100644
--- a/apps/docs/proxy.ts
+++ b/apps/docs/proxy.ts
@@ -1,5 +1,6 @@
import type { NextRequest } from "next/server";
import { NextResponse } from "next/server";
+import { proxy as localeProxy } from "nextra/locales";
/**
* Browsers or other localhost apps (e.g. MSW) may request `/mockServiceWorker.js`.
@@ -18,9 +19,12 @@ export function proxy(request: NextRequest) {
},
);
}
- return NextResponse.next();
+ return localeProxy(request);
}
export const config = {
- matcher: "/mockServiceWorker.js",
+ matcher: [
+ "/mockServiceWorker.js",
+ "/((?!api|_next/static|_next/image|favicon.ico|icon.svg|apple-icon.png|manifest|_pagefind).*)",
+ ],
};