XGC2

文档站，从写作开始 ​

内容使用 Markdown 编写，主题统一处理布局、字体、代码呈现与搜索。

这套文档站由 VitePress 驱动。内容与渲染配置分开存放，不依赖 XGC2 应用运行时；发布的是独立静态文件，而不是一个需要常驻服务的应用。

本地启动 ​

环境要求为 Node.js 22 或更新版本。安装锁定依赖后，使用仓库脚本启动开发服务：

sh
npm ci
npm run dev

打开 http://127.0.0.1:5176/docs/。开发地址显式包含 /docs/，与线上部署的基础路径保持一致。

保持路径真实

不要通过省略基础路径来绕过检查。页面链接与静态资源都应在 /docs/ 下工作，这样本地预览和发布后的行为才一致。

内容与主题分开 ​

新增文档放在 content/，主题与站点配置放在 site/。公开图片等静态资源放在 content/public/。

位置职责不应承担
content/可阅读的 Markdown 内容页面级样式补丁
site/.vitepress/theme/布局、字体与交互具体产品事实
content/public/公开内容资源私有配置与凭据

最小页面 ​

每篇文档从一个清晰的标题和一段说明开始。Frontmatter 提供页面元信息，正文保留正常阅读顺序：

md
---
title: 页面名称
description: 一句话说明读者能获得什么。
---

# 页面名称

从这里进入正文。

页面层级 ​

正文只使用一个一级标题。二级标题划分主要任务，三级标题解释任务内部的步骤或概念；不要把标题层级当作单纯的字号工具。

标题应准确概括本节内容，并保持连续层级，方便读者快速定位。

代码应当可以执行 ​

示例命令必须来自真实工作流，并注明执行前提。不要为了让页面显得完整而虚构参数、接口或返回结果。

sh
npm ci
npm run dev
sh
npm run build
npm run check

行内标识符使用 monospace，普通术语和数值读数不滥用代码格式。较长的配置或命令通过代码块横向滚动，不挤压正文阅读列。

发布前检查 ​

构建会生成完整静态站点，现有测试会检查发布边界、资源顺序和 HTTPS 校验等行为：

sh
npm run build
npm run check

构建产物位于 site/.vitepress/dist/。推送到主分支会自动执行测试和构建，通过后经 SFTP 发布，再核对公开 HTTPS 字节；源文件和服务器管理权限不属于这条发布链路。

不把构建成功当作全部验收

涉及导航、搜索、代码复制或主题切换的改动，还需要在真实浏览器里完成一次对应操作。