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

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:

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)

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.
No frontmatter on content pages — only index.md uses it (layout: home) and 404.md (noindex head).
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).
Internal cross-references between chapters use relative ../ paths from the page's own directory.
Body content contains no image references; images live only in index.md and public/.
Structure pages with ##/### headings only (outline is [2, 3]). Custom containers: :::tip 概述 is the standard page opener; :::warning used sparingly.
Content language is Chinese throughout (tables, headings, prose), with English technical terms (routes, table names, code identifiers) kept as-is.
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).

7.3 KiB Raw Blame History