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.