Afterglow

简体中文

English
English

简体中文

English
English

外观

文档与 Wiki 维护 ​

单一真源 ​

主要阅读入口是 GitHub Pages 上的 VitePress 双语文档网站。每篇文章每种语言只维护一份：

  • 中文：docs/wiki/，保留现有文件名和仓库相对链接。
  • 英文：docs/en/，一篇文章一个独立 Markdown 文件。
  • 页面对应关系：docs/pages.json，slug 在 /en/ 和 /zh/ 下相同。
  • 网站固定文案：docs/.vitepress/locales/en.mjs、zh-CN.mjs，一种语言一个文件。

.site/、.vitepress/dist/ 和 Wiki checkout 都是生成结果。修改文章时在同一 PR 同步两种语言，不能用英文摘要代替完整译文。

README.md（英文）与 readme/README.zh-CN.md（中文） 是同等项目入口。其中架构图是刻意保留的摘要，架构变更时应与两份完整架构文章一同更新。前后端 README 保留各自的包级入口用途。

页面组织 ​

新增页面时：

  1. 在 docs/wiki/ 添加中文文章，在 docs/en/ 添加英文对应文章。
  2. 在 docs/pages.json 添加共同 slug、中文文件名和导航分组；网站导航标题在各语言模块的 pages 中维护。
  3. 两种语言的标题层级与章节顺序保持对应，切换语言才能保留所在章节。
  4. 从文档首页和相关文章添加可发现链接。
  5. 提交前运行检查、测试与生产构建。

生成后的地址为 /en/<slug>.html、/zh/<slug>.html，语言首页为 /en/、/zh/。源文章使用相对 .md 链接，方便在 GitHub 浏览；生成的章节 ID 用于对应语言切换，可读标题别名保留直接章节链接。

网站默认英文。首次访问根入口时，浏览器语言列表包含简体或繁体中文就自动中文，否则英文。下拉框手选保存在 afterglow.docs.locale 并优先使用。直接打开特定语言文章时保持该 URL 的语言，保证分享链接可预期。

本地开发需要 Python 3、Node.js 20+：

bash
cd docs
npm ci
npm run dev

启动 VitePress 前会生成页面；开发时修改源文章后重新运行 npm run prepare:docs。检查和预览：

bash
npm run check
npm test
npm run build
npm run preview

默认基础路径为 /Afterglow/。自定义域名或根路径部署使用 DOCS_BASE=/ npm run build；不同项目名使用 DOCS_BASE=/your-project/。Wiki 工作流的仓库变量 DOCS_SITE_URL 应与实际网站地址一致。

首次启用 GitHub Pages ​

维护者首次设置：

  1. 在仓库 Settings → Pages 中将 Source 选择为 GitHub Actions。
  2. 将文档源码与工作流合入 main，或在目标分支手动运行 docs-pages。
  3. 从 github-pages 环境及部署输出查看实际网址。

默认地址为 https://kldhsh123.github.io/Afterglow/。Fork 按仓库名称计算基础路径；自定义域名还需设置 Pages 域名并匹配基础路径。工作流支持手动输入 base_path 和仓库变量 DOCS_BASE。

Wiki 可选。初始化时在 Settings 启用 Wikis、限制为协作者编辑，并先创建 Home 页让 Wiki Git 仓库可 clone。sync-wiki 默认用 GITHUB_TOKEN；仓库策略要求独立凭据时使用 WIKI_TOKEN。

同步行为 ​

.github/workflows/docs-pages.yml 对文档 PR 做检查和构建，不发布；推送到 main、发布 Release 或手动运行时构建并部署静态产物。Release 使用对应 tag 源码。PR 不获得部署权限，部署共用 concurrency group 避免并发覆盖。

.github/workflows/sync-wiki.yml 对文档 PR 做校验；只有 Release 和手动运行才写 Wiki。生成的平铺镜像保留旧中文页名，英文页使用 EN-<slug>，每页都有网站入口和对应语言链接。侧边栏同时提供两种语言。保留源中文标题以兼容旧 Wiki 章节链接。

Wiki checkout 使用 rsync --delete 严格镜像生成结果并排除 .git/；只有差异时才普通提交并推送，不 force push。发布不会改写仓库源文章。

生成脚本 ​

.github/scripts/prepare_docs.py 读取两种语言源文章和页面映射，校验对应章节数量、源文件、内部页面链接，拒绝把源目录作为输出，生成网站页面树或平铺 Wiki。.github/scripts/prepare_wiki.py 仅处理生成 Wiki 中的链接校验与转换。

在仓库根目录安全预览 Wiki：

bash
python3 .github/scripts/prepare_docs.py wiki --output /tmp/afterglow-wiki-preview

不要直接把源目录传给 Wiki 链接转换器，它会原地改写输入。网站的渲染链接和翻译结构另由 docs/scripts/ 检查。

参考：

配置编辑器字段由后端 Settings、两份 .env.example 模板及双语环境变量参考生成。新增参数时须同步这些文件；构建会检查遗漏和模板值差异。编辑器界面文案放在站点语言文件中，Node 测试覆盖文件解析与生成。

品牌图片以 assets/brand/ 为准，生成器将选用的 logo 与 favicon 复制到网站生成目录。README 与导航栏使用现有浅色/深色版本，调整标志时应修改原始资源。

AGPL-3.0-or-later

Afterglow