versioning.mdx

title	多版本文档发布
description	本站由 Fumadocs + Next.js 静态导出构建，通过 GitHub Actions 发布到 GitHub Pages。

本站使用 Fumadocs（Next.js 静态导出）构建。内容和导航都在仓库里，构建产物是一份纯静态目录，可以直接放到任意静态托管上。

站点结构

路径	作用
content/docs/	文档正文（*.mdx）与侧边栏顺序（meta.json）
src/app/	路由、布局、搜索接口与 OG 图片生成
src/components/	MDX 组件（Hero、ConfigPreview 等）
tools/config-form/	配置表单组件源码，构建后输出到 public/config-form/

本地构建与预览

bun install
bun run config-form:build   # 构建 public/config-form/ 下的配置表单组件
bun run dev                 # 开发服务器

bun run build               # 静态导出到 out/
bun run start               # 本地预览 out/

next.config.mjs 打开了 output: 'export' 和 trailingSlash，因此每个页面都导出为 路由/index.html，GitHub Pages 这类不做无扩展名重写的静态托管也能正确解析。

发布 v4

主版本发布在站点根路径，由 GitHub Actions 在 main 上完成：

- run: bun install --frozen-lockfile
- run: bun run config-form:build
- run: bun run build
- uses: actions/upload-pages-artifact@v3
  with:
    path: out

首次部署时需要在仓库的 Pages 设置里把来源指向 GitHub Actions。

保留旧版本

需要同时提供 v3 旧文档时，把它发布到版本子目录，而不是替换根路径：

# 在 AthenaDocsNG 仓库中，检出 v4 改版前的提交
git checkout <v3-commit>

# 用当时的工具链构建旧文档
bun install
bun run build

# 把产物放到新站点输出的子目录后再整体发布
mkdir -p ../site/v3 && cp -r out/. ../site/v3/

站点根目录始终对应 main 上的最新文档，旧版本放在 v3/、v4/ 这类子目录下。

文档维护约定

• 新增页面后，把它的文件名写进同级 meta.json 的 pages，否则不会出现在侧边栏。
• 页面标题写在 frontmatter 的 title，摘要写在 description，两者都会参与搜索与 OG 图片生成。
• docs/athena-v4-vision-and-evolution-notes.md（YesImBot 主仓库）描述架构演进，内容变化时同步更新本站对应页面。