54 lines
4.9 KiB
Markdown
54 lines
4.9 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## What this repository is
|
||
|
||
Documentation site for **RXThinkCMF** (Laravel 13 + Vue3 + NaiveUI admin framework), built with VitePress 1.x. This folder contains **only the docs** — the product code lives in separate Gitee repositories. All content, sidebar labels, and UI text are in **Simplified Chinese**; write new content in Chinese.
|
||
|
||
Important context discovered only by reading multiple files:
|
||
|
||
- The git repository root is the **parent directory** (`…/v3/document/`), which holds 9 sibling variant doc sites (ThinkPHP6/8/Laravel13 × Layui/EleVue/AntdVue/NaiveVue) with near-identical structure. `git status` may show sibling folders; each has its own `package.json`, `.vitepress/`, `zh/`, `index.md`.
|
||
- This variant's content was adapted from the EleVue sibling and has been **converted to NaiveUI** (2026-10). ElementPlus/EleVue references remain **only where intentional**: the 12-row variant table in `zh/introduction.md` (each row links a different real product), the nav dropdowns in `.vitepress/config/zh.ts` (cross-links to sibling doc sites), the commented-out `en.ts`, and the product-line sentence in `zh/other/sponsor.md`. When writing new factual content, verify against the actual NaiveUI product at `D:\xampp8.2\htdocs\v3\RXThinkCMF_Laravel13_NaiveVue\ui` rather than copying sibling pages blindly; `RXThinkCMF_ThinkPhp6_NaiveVue` is a previously converted reference with the same conventions (naive-ui ^2.40.0, Vite ^5.4.3, `NTag`/`NAvatar`, `useMessage`/`useDialog` from `naive-ui`, `window.$message`/`$dialog` via `createDiscreteApi`, DB `rxthinkcmf.laravel13.naivevue`).
|
||
- Code samples and paths in the docs (e.g. `app/`, `ui/src/store/modules/`) refer to the external product repository, not files in this repo.
|
||
|
||
## Commands
|
||
|
||
- `pnpm docs` — dev server (`vitepress dev .`)
|
||
- `pnpm docs:build` — production build. **This is also the validation step**: VitePress fails the build on dead internal links (only `localhost` links are exempt, see `ignoreDeadLinks` in `.vitepress/config/index.ts`). Always run it after adding, renaming, or reordering pages. Takes ~40s; expected warnings: `gitignore` language fallback, chunk-size notice.
|
||
- `pnpm docs:preview` — serve the built site
|
||
|
||
README specifies pnpm, though the committed lockfile is `yarn.lock`. There is no test suite or linter in this repo.
|
||
|
||
## Architecture
|
||
|
||
- `index.md` — home page (`layout: home`, frontmatter-driven hero/features, imports `HomeSponsors` from the theme).
|
||
- `zh/` — all content, organized into chapter directories (`quickstart/`, `guide/`, `architecture/`, `core/`, `modules/`, `frontend/`, `deploy/`, `standards/`, `appendix/`, ...). Files are numbered by chapter position (e.g. `zh/core/jwt.md` is section 5.1).
|
||
- `.vitepress/config/index.ts` — entry; merges shared config with the `zh` locale as root (`zh-CN`). The English locale (`.vitepress/config/en.ts`) is entirely commented out — leave it that way unless asked.
|
||
- `.vitepress/config/zh.ts` — nav + the full sidebar tree (~550 lines). **The central file to update when adding, renaming, or reordering pages.** Chapter comment banners record renumbering decisions.
|
||
- `.vitepress/config/shared.ts` — global theme config: custom `slugify`, markdown code themes, attribute delimiters, head/meta tags, social links, local search provider.
|
||
- `.vitepress/theme/` — extends the default theme: `Layout` slots (custom hero image, `AsideSponsors`), globally registered components (`VideoModuleLink`, `vImageViewer`), `styles/vars.css`, and the image-viewer plugin.
|
||
- `public/` — static assets (logos, banners, sponsors, `banner.js`).
|
||
- `.vitepress/translation-status.json` — tracks the zh translation hash/date.
|
||
|
||
## Content conventions
|
||
|
||
- Every page's H1 is `<章号>.<节号> <标题>` and **must match its sidebar label exactly** (sidebar `"5.16 统一响应与异常抛出"` → `zh/core/exception.md` starts with `# 5.16 统一响应与异常抛出`).
|
||
- The H1 is immediately followed by a summary block:
|
||
```
|
||
:::tip 概述
|
||
一两句话概括本页内容。
|
||
:::
|
||
```
|
||
- Container directives in use: `:::tip`, `:::info`, `:::warning`, `:::danger`.
|
||
- Internal links are root-absolute with an explicit `.html` extension: `[5.16 统一响应与异常抛出](/zh/core/exception.html)`.
|
||
- Use fenced code blocks with a language tag; use `::: code-group` for side-by-side file examples.
|
||
- Markdown attribute delimiters are customized to `%{` / `}%` (see `shared.ts`).
|
||
|
||
## Adding or renumbering pages
|
||
|
||
1. Create/edit the file under `zh/<section>/` following the conventions above.
|
||
2. Add or update its entry in the sidebar in `.vitepress/config/zh.ts` — pages not in the sidebar are unreachable from navigation.
|
||
3. If renumbering, the H1, sidebar label, and all cross-references to that section number elsewhere in `zh/` must stay in sync.
|
||
4. Run `pnpm docs:build` to confirm no dead links.
|