# 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.