Guaifinition Docs · Astro 版

原 Next.js 站点（guaifinition-docs）的 Astro + Markdown 架构迁移版。 内容与设计保持不变，渲染层改为 Astro 静态生成（SSG）。

架构

content-library/*.md + index.json        （原站内容源，仓库内自带 content-library/）
        │  npm run prep
        ▼
src/content/docs/<course>/<slug>.md     187 篇（178 篇内容库 + 9 章 DeepSeek 报告），Astro Content Layer
        │  astro build
        ▼
dist/                                   213 个静态页 + search-index.json

设计（复刻 developers.openai.com，同 flash 4.1 文档站）

页面结构四要素：

1. 顶部横向关键词导览 — 分编（7 个集合）作为全局关键词；进入课程后二级栏切换为该课程的章节横向导览
2. 左侧边栏：站点总目录 — 分编 → 24 门课程 → 当前课程展开章节（滚动定位当前项）
3. 右侧边栏：本页目录 — 正文 H2/H3，滚动高亮（IntersectionObserver）
4. 底部导航 — 上一篇 · 回到顶部 · 下一篇

样式来源（真实 CSS，非模板套壳）：

文件	内容
src/styles/tokens.css	从 developers.openai.com 实测抽取的设计 token（明/暗双套：字体、灰阶、语义色、尺寸变量）
src/styles/site.css	三栏布局与组件样式（header 64px / subnav 48px / sidenav 218px / 内容 872px / TOC 200px，含 KaTeX、表格、代码块、搜索弹窗）
src/styles/extra.css	本站扩展：站点总目录嵌套、首页目录卡片、课程页列表、三槽页脚

交互（原生 JS，无框架运行时）：主题切换、TOC scrollspy、Ctrl/⌘+K 搜索（索引按需拉取 /search-index.json，280KB）、代码块复制、左栏当前章节自动滚入视野。

层	位置
内容	src/content/docs/**/*.md（frontmatter: title / course / courseTitle / module / order / summary / tags …）
内容管线	scripts/prep-content.mjs（索引 → frontmatter；并把 DeepSeek-V4.1-Flash 报告并入）
数据层	src/lib/content.ts（课程/分编/前后篇/标题锚点）
布局	src/layouts/DocsLayout.astro + src/components/*.astro
页面	src/pages/index.astro、src/pages/courses/[course].astro、src/pages/courses/[course]/[slug].astro
样式	src/styles/tokens.css + site.css（复刻 developers.openai.com）+ extra.css（本站扩展）
资源	public/content-assets/（原站 42MB 图片）、public/assets/media/（DeepSeek 报告 19 张图）

Markdown 管线：remark-gfm + remark-math → rehype-raw + 自定义标题 id（与站点 slugify 一致）+ rehype-katex。

命令

npm run prep     # 从原站 content-library + DeepSeek 报告生成 src/content/docs
npm run dev      # 开发服务器 http://localhost:4400/guaifition-docs/
npm run build    # 静态构建 → dist/
npm run preview  # 预览构建产物

书签页的 GitHub 实况（gh CLI）

content-library/ai-bookmarks-index.md 是自包含的单一源，页首「最近添加」是滚动置顶位： 只保留最新收录的一条（正文与其真实分节里的条目一致，属有意重复展示）， 新增书签时用新条目替换它，被替换下来的条目继续留在原分节。正文其余部分人工维护， 唯一由机器写入的是「GitHub Star 清单」分节 —— 分节顶部一条校验元信息 + 每个仓库一段 实况（校验 …）（★ / fork / 最近推送 / 语言 / 许可证 / 已 star 日期）。

npm run verify:stars            # 走本地 gh CLI 校验并回写该分节（幂等，只动这一节）
node scripts/verify-stars.mjs --no-write   # 只出报告，不改页面

产物留档在 content-sources/bookmarks/：stars.json（结构化实况）+ stars.report.md （含「账号已 star 但清单未收录」的差异分析：已在本页其它分节 / 正文提到过 / 完全缺失）。 其余内容源同样留档在 content-sources/（andrew-ng/research/ 为深度研究的过程与质检全量）。

质量检查

npm run check:links   # 全站体检：页面存在性 / 站内链接 / 锚点 / 静态资源 / 外链统计
npm run check:slug    # 校验三处 slug 规则一致（astro.config / lib / prep）

改了 markdown 配置（remark/rehype 或 slug 规则）后，需清缓存再构建： rm -rf .astro dist node_modules/.astro && npm run build，否则 Astro 会复用旧的渲染缓存。

部署

base 设为 /guaifition-docs（GitHub Pages 项目站）。已附 .github/workflows/deploy-pages.yml：

1. 把本目录内容推到一个仓库（可替换原仓库内容或另建仓库）
2. 仓库 Settings → Pages → Source 选 GitHub Actions
3. push 到默认分支即自动构建并发布

自定义域名或根路径部署时，改 astro.config.mjs 的 base（或用 PUBLIC_BASE_PATH 环境变量覆盖）。

与原站的差异

• 渲染：Next.js（RSC + react-markdown）→ Astro SSG（构建期渲染 Markdown，无客户端渲染负担）
• 内容：正文由 content-library/*.md 直接读取 → 迁入 Astro Content Layer（frontmatter 化，可类型校验）
• 设计：原站书页风格 → OpenAI 官方文档式三栏布局（顶部关键词导览 + 左栏站点总目录 + 右栏本页目录 + 三槽页脚）
• 交互：React 组件 → 原生内联 JS（主题切换、scrollspy、搜索、复制、侧栏定位）
• 新增：DeepSeek-V4.1-Flash 技术报告中文版（9 章，含 KaTeX 公式、19 张图表、代码块）
• 新增：AI 书签索引（54 条 AI 工程 / Agent / 算法 / 课程与资讯书签，含 gh CLI 实况校验的 Star 清单）
• 新增：Andrew Ng 产出档案（2026-06 ~ 09 的 The Batch / Letters / X 索引 + 18 节、约 7.3 万字深度研究报告）
• 新增：全站搜索走 /search-index.json（187 篇 × 全部 H2/H3，按需加载，不内联进每个页面）