Deepsight

Appearance

官网与文档站维护 ​

本文档说明 Deepsight 官网与文档站的目录结构、更新方式和部署流程。站点基于 VitePress，源码放在仓库内的 site/ 目录，文档真源仍然保持在根目录 docs/。

1. 目录分工 ​

text
Deepsight/
├── docs/                      # 文档真源
├── site/                      # VitePress 站点
│   ├── index.md               # 官网首页
│   ├── guide/                 # 构建前生成的站内文档副本（不追踪）
│   ├── public/assets/         # 从 docs/assets 同步的文档资源（不追踪）
│   ├── public/brand/          # 站点品牌资源（追踪）
│   ├── scripts/sync-docs.mjs  # 文档同步脚本
│   └── .vitepress/            # 站点配置与主题
└── .gitlab-ci.yml             # 主发布流程：GitLab CI 构建站点并推送到 GitHub Pages 仓库
  • docs/：作为文档的单一事实来源，日常只需要维护这里。
  • site/index.md：官网首页，单独维护，不从 docs/ 自动生成。
  • site/guide/：由脚本自动生成，不要手动编辑。
  • site/public/assets/：由脚本从 docs/assets/ 同步生成。
  • site/public/brand/：站点 Logo、favicon 等品牌资源，需要纳入版本控制。

2. 本地更新流程 ​

首次使用前，请先安装 Node.js 20 或更高版本，然后执行：

bash
cd site
npm install

日常维护站点时，按下面流程进行：

  1. 修改根目录 docs/ 下的设计文档、开发文档或安装文档
  2. 如需调整官网文案，再修改 site/index.md
  3. 在 site/ 目录运行本地预览
bash
cd site
npm run docs:dev

这个命令会先执行 scripts/sync-docs.mjs，把 docs/ 中的内容同步到站点目录，然后启动本地开发服务器。

3. 构建命令 ​

仅同步文档：

bash
cd site
npm run docs:sync

构建静态站点：

bash
cd site
npm run docs:build

构建结果位于：

text
site/.vitepress/dist/

以下目录不应纳入 Git 追踪：

  • site/guide/
  • site/public/assets/
  • site/.vitepress/dist/
  • site/node_modules/

4. 自动同步范围 ​

同步脚本当前会处理以下内容：

  • docs/*.md
  • docs/dev/*.md
  • docs/use/*.md
  • docs/assets/*

并自动完成以下转换：

  • 文档复制到 site/guide/
  • 图片路径从相对路径改写为 /assets/...
  • 按 docs/ 目录结构自动映射到站内路径
  • 对少数首页级文档应用稳定 slug 别名，例如 01_deepsight.md -> overview.md

后续新增普通文档时，不需要修改同步脚本，脚本会自动发现并映射。只有在你希望某个文档使用特定 slug 时，才需要调整：

  • site/scripts/sync-docs.mjs 中的 slugOverrides
  • site/.vitepress/config.ts 中的 sidebar

5. 主发布流程：GitLab CI -> GitHub Pages 仓库 ​

推荐方案是：

  1. 主代码仓库继续托管在学校 GitLab
  2. 单独创建一个 GitHub 仓库，仅用于托管静态站点
  3. GitLab CI 在主仓库里构建 site/.vitepress/dist
  4. GitLab CI 将构建产物推送到 GitHub Pages 仓库

这样做的结果是：

  • GitHub 不需要托管你的完整源码
  • GitHub 仓库里只保留网站静态文件
  • GitHub Pages 只承担站点发布职责

5.1 准备一个 GitHub Pages 仓库 ​

创建一个公开 GitHub 仓库，例如：

text
your-github-user/deepsight-site

这个仓库只用于承载静态站点内容，不需要同步 Go 源码。

5.2 配置 GitHub Pages 仓库 ​

在该 GitHub 仓库中：

  1. 进入 Settings -> Pages
  2. 选择从分支部署
  3. 选择 main 分支和 / (root) 目录

如果后续绑定了自定义域名，GitHub Pages 会直接从这个仓库对外提供站点。

5.3 在 GitLab 中配置 CI 变量 ​

在 GitLab 项目的 Settings -> CI/CD -> Variables 中添加：

  • GITHUB_PAGES_REPO
    • 值示例：your-github-user/deepsight-site
  • GITHUB_PAGES_BRANCH
    • 值示例：main
  • GITHUB_PAGES_TOKEN
    • GitHub Personal Access Token，至少需要目标仓库的写权限

建议将 GITHUB_PAGES_TOKEN 标记为 masked 和 protected。

如果你使用的是 GitHub Fine-grained PAT，至少授予目标仓库：

  • Contents: Read and write
  • Metadata: Read

如果你使用的是 Classic PAT，常见做法是授予：

  • repo

5.4 发布触发条件 ​

仓库中的 .gitlab-ci.yml 会在 main 分支发生以下变更时触发发布：

  • docs/**
  • site/**
  • README.md
  • .gitlab-ci.yml
  • scripts/ci/deploy_site_to_github_pages.sh

CI 任务会执行：

  1. 安装站点依赖
  2. 执行 npm run docs:build
  3. 将 site/.vitepress/dist 推送到 GitHub Pages 仓库

5.5 首次部署检查清单 ​

首次接通这条链路时，建议按以下顺序检查：

  1. 在本地确认 cd site && npm run docs:build 可以成功
  2. 确认 GitHub Pages 目标仓库已经创建
  3. 确认目标仓库默认分支与 GITHUB_PAGES_BRANCH 一致
  4. 确认目标仓库已开启 Pages，并指向该分支根目录
  5. 确认 GitLab CI 变量已经配置完毕
  6. 向 GitLab 主仓库的 main 分支推送一次与站点相关的提交
  7. 在 GitLab CI 查看 deploy_site_to_github_pages 任务日志
  8. 到 GitHub Pages 目标仓库确认静态文件是否已经更新

6. 自定义域名 ​

如果使用自己的域名，建议直接将 GitHub Pages 绑定到自定义域名，例如：

  • docs.example.com
  • deepsight.example.com

此时在 site/.vitepress/config.ts 中使用：

ts
base: "/"

然后在 GitHub Pages 仓库的 Pages 设置中填写自定义域名，并在你的 DNS 提供商处配置对应记录。

如果你希望在每次 GitLab CI 发布时保留 GitHub 仓库中的 CNAME 文件，当前发布脚本已经默认不会删除它。

7. 维护纪律 ​

  • 技术文档只维护一份，优先修改根目录 docs/
  • 不要手动编辑 site/guide/ 下的生成文件
  • 官网首页是对外叙事层，不要把所有技术细节都堆进去
  • 图片与架构图统一放在 docs/assets/
  • 站点改动合并前，至少本地运行一次 npm run docs:build
  • 正式发布链路以 GitLab CI 为准，GitHub 仓库只作为静态站点发布目标

Apache 2.0 Licensed

Copyright © Deepsight