66 lines
7.3 KiB
Markdown
66 lines
7.3 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What this is
|
|
|
|
A VitePress 1.3.4 documentation site (Chinese, zh-CN) for the EasyGoAdmin project (GoFrame v2 + Vue3 + ElementPlus). All content is Markdown under `zh/`; there is no application source code here. No lint/test tooling exists — only dev/build/preview.
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
yarn install # yarn.lock is the committed lockfile (node_modules may be absent — it gets deleted manually)
|
|
yarn docs # dev server: vitepress dev .
|
|
yarn docs:llms # regenerate public/llms.txt only
|
|
yarn docs:build # regenerate llms.txt + static build to .vitepress/dist
|
|
yarn docs:preview # preview built site
|
|
```
|
|
|
|
There is no single-page test/run command; to check a page, run the dev server or `docs:build`. Build also catches dead links — only `localhost` links are exempt via `ignoreDeadLinks` in `.vitepress/config/index.ts`.
|
|
|
|
The SEO hooks in `.vitepress/config/seo.ts` depend only on Node builtins, so they can be smoke-tested without node_modules:
|
|
|
|
```bash
|
|
node --experimental-strip-types -e "import('./.vitepress/config/seo.ts').then(m => console.log(typeof m.createSeoHooks))"
|
|
```
|
|
|
|
## Repository context
|
|
|
|
The git repo root is `E:/EasyGoAdmin_V3/document`, which contains **16 sibling documentation projects** (EasyGoAdmin_{Beego,Gin,GoFrame,Iris}_{AntdVue,EleVue,Layui,NaiveVue}). This project is `EasyGoAdmin_GoFrame_EleVue`. Git status/commits therefore span all 16 — scope your changes and commits to this directory unless told otherwise. Branch: `master`.
|
|
|
|
## Architecture (the parts that require multiple files to understand)
|
|
|
|
- `.vitepress/config/index.ts` — merges `sharedConfig` + locale config and wires the SEO hooks via `createSeoHooks(zhConfig.themeConfig?.sidebar)`. The **root locale is Chinese** (`link: "/"`); the English locale in `en.ts` exists but is fully commented out here.
|
|
- `.vitepress/config/zh.ts` — the single source of truth for nav and sidebar. The sidebar manually lists **every** page with a numbered title (e.g. `{ text: "📄 3.3 DAO 数据层", link: "/zh/guide/model.html" }`). Adding, renaming, or renumbering a page requires a matching edit here; the site gives no warning if you forget (dead-link checks do not cover the sidebar). Also exports `zhSearch` (Algolia config) which is never imported — local search in `shared.ts` is what actually runs.
|
|
- `.vitepress/config/shared.ts` — site-wide head/meta, `titleTemplate` ("… | EasyGoAdmin 开发文档"), custom `slugify` (anchors), markdown code themes, local search, Gitee edit links.
|
|
- `.vitepress/config/extract.mjs` — **single source of truth for SEO text**: `SITE_URL` (http — the docs subdomain serves a mismatched Tencent CDN cert, so HTTPS fails; flip this one constant when the cert is fixed), `SITE_DESCRIPTION`, `stripNumberPrefix`, `extractDescription` (first sentence of the `:::tip` block → meta description), `extractFaqs`. Zero-dependency ESM so both the VitePress config (esbuild-bundled) and the llms.txt script can import it; types in `extract.d.mts`.
|
|
- `.vitepress/config/seo.ts` — build-time SEO hooks (`createSeoHooks(sidebar)`): `transformPageData` (per-page title with chapter-number prefix stripped + tip-derived description), `transformHead` (canonical, og:*/twitter:* tags, JSON-LD: WebSite+Organization on home, TechArticle+BreadcrumbList+FAQPage on content pages, git-based `dateModified`), `sitemap.transformItems` (git `lastmod`, filters 404). Breadcrumb labels are derived from the zh.ts sidebar at build time — keep them in sync automatically by editing zh.ts only. Depends only on Node builtins (smoke-testable without node_modules).
|
|
- `.vitepress/theme/index.ts` — extends the default theme: overrides the home hero image, registers `AsideSponsors` in the `aside-ads-before` slot, registers `VideoModuleLink` globally, and wires `vitepress-plugin-image-viewer`. `VideoModuleLink` is registered but not yet referenced by any Markdown page. Theme data lives in `.vitepress/theme/components/sponsors.json`.
|
|
- `.vitepress/theme/styles/vars.css` — CSS variables; `appearance: "light"` is the default.
|
|
|
|
## Content conventions (enforce these when creating/editing pages)
|
|
|
|
1. **Every page** starts with `# N.N 标题` (or `# A. 标题` for appendices) matching its sidebar numbering exactly, followed by a `:::tip 概述` block summarizing the page (141/143 pages follow this; `zh/changelog.md` and `zh/other/contributing.md` are the exceptions). The tip's **first sentence becomes the page's meta description and llms.txt entry** — write it as a self-contained answer, not a lead-in.
|
|
2. No frontmatter on content pages — only `index.md` uses it (`layout: home`) and `404.md` (noindex head).
|
|
3. **Sidebar links** use the `.html` suffix (`/zh/guide/model.html`); **in-body internal links** are relative and extensionless (`[5.10 字典模块](../core/dict)`). Keep in-body links free of absolute paths and `.html` suffixes (external links to other sites are fine).
|
|
4. Internal cross-references between chapters use relative `../` paths from the page's own directory.
|
|
5. Body content contains no image references; images live only in `index.md` and `public/`.
|
|
6. Structure pages with `##`/`###` headings only (outline is `[2, 3]`). Custom containers: `:::tip 概述` is the standard page opener; `:::warning` used sparingly.
|
|
7. Content language is Chinese throughout (tables, headings, prose), with English technical terms (routes, table names, code identifiers) kept as-is.
|
|
8. **Freeze chapter numbering once published.** Sidebar numbers are duplicated in prose cross-references ("详见 5.10"), baked into JSON-LD breadcrumbs, llms.txt entries, and likely external inbound links — renumbering breaks all of them at once.
|
|
|
|
## Gotchas
|
|
|
|
- Two pages (`zh/course.md`, `zh/quickstart/environment.md`) contain ```mermaid fences, but **no mermaid plugin is installed** — they render as plain code blocks. `vitepress-plugin-group-icons` is in package.json but never wired into config.
|
|
- `.vitepress/translation-status.json` is not read by any code.
|
|
- Numbered sidebar titles are duplicated in prose cross-references (e.g. "详见 5.10"); keep both in sync when renumbering (and see convention 8 — prefer not renumbering at all).
|
|
- `README.md` is empty — don't expect setup docs there.
|
|
|
|
## SEO/GEO tooling
|
|
|
|
- **`public/llms.txt` is generated** by `scripts/generate-llms-txt.mjs` (H1 + tip first sentence per page, grouped by sidebar chapter). It runs automatically before `docs:build`; run `yarn docs:llms` after adding pages if you only need the file refreshed. Do not hand-edit it.
|
|
- **`public/robots.txt`** allows all crawlers explicitly (incl. GPTBot/ClaudeBot/PerplexityBot) and points at `sitemap.xml`.
|
|
- **sitemap.xml** comes from VitePress's built-in `sitemap` option in `config/index.ts` (hostname + git lastmod via `seo.ts`); it only exists after `docs:build`, not in dev.
|
|
- **`SITE_URL` lives only in `extract.mjs`** — canonical, og:url, JSON-LD, sitemap, and llms.txt all derive from it. It is `http://` because the docs subdomain's TLS cert is a CDN default (`*.cdn.myqcloud.com`); when the cert is fixed, change that one constant (zh.ts `META_URL` duplicates it for og/twitter static tags — update both).
|
|
- Baidu analytics is embedded in zh.ts head; no Baidu/Google site-verification meta is present (manual step if webmaster tools are added).
|