PyCaret 官方站点 `apps/site` 深度解析：Next.js 15 + MDX 文档站的架构、内容管线与部署实践

apps/site是 PyCaret 4.0 的公开门户，承载官网首页、文档（Docs）、自动生成的 API 参考（Reference）、博客（Blog）与更新日志（Changelog）五个核心板块，以单一 Next.js 15 应用形态部署。本文围绕该目录的 README 与仓库源码，完整梳理其技术栈、本地运行与构建流程、四类内容的生成与维护管线、CI/CD 部署方式，以及面向 AI Agent 的维护约定，帮助你快速上手贡献文档、理解内容自动同步机制，并复用到自己的文档站点建设中。

站点定位：一个应用、五种内容

apps/site是 PyCaret 仓库中面向公众的营销与文档站点（部署于pycaret.org），与仓库内另一个 React 控制平面应用apps/web（位于 apps/web）职责分离：前者是内容与营销站，后者是实验管理 UI。其独特之处在于——站点上几乎所有产物要么由本目录生成，要么从 monorepo 其他位置自动导入，这为内容维护提供了「一处修改、全站同步」的工作流。

从 apps/site/app 的目录结构可以看到五个顶层路由：

「自动生成/自动导入的内容不要手改」是理解整个站点的关键心智模型，后文会逐一展开。

技术栈：为什么这样选型

README 明确列出的技术栈如下，结合 apps/site/package.json 中的实际依赖可以相互印证：

• Next.js 15 + App Router：依赖声明为next@^16.2.4，但 README 与代码注释仍以 Next.js 15 语义编写（next.config.mjs 中的注释提到 Next.js 16 将typedRoutes提升为顶层选项，说明仓库正跟随上游版本演进）。
• TypeScript + Tailwind CSS：类型检查由tsc --noEmit完成（见package.json的typecheck脚本），Tailwind 配置位于 tailwind.config.ts，色板（ink/accent）刻意与仪表盘应用apps/web/src/index.css保持一致，保证品牌统一。
• MDX 内容（next-mdx-remote-client）：不采用构建期编译的@next/mdx插件，而是在请求期通过 MdxRenderer.tsx 渲染 MDX，好处是内容可以来自任意来源（文件系统、CMS），且自动导入的发布说明中包含<、{等字符时不会被 MDX 的 JSX 解析器误伤（渲染时显式使用format: 'md'）。
• Shiki 语法高亮（服务端渲染、零运行时）：CodeBlock.tsx 在服务端调用shiki的codeToHtml把代码块预渲染为 HTML，客户端不加载任何高亮 JS，这对 SEO 与首屏性能都很友好，并使用github-light主题匹配站点的排版色板。
• griffe API 自动生成（Python → JSON 树）：scripts/gen_api_tree.py 使用与 mkdocstrings 相同的静态分析器 griffe 扫描pycaret包，输出content/api-tree.json供 Next.js 的/reference路由渲染。

选择 griffe 而非 Python 运行时inspect的原因在脚本 docstring 中说明得很清楚：griffe 静态解析源码，因此sktime、pyod等可选/重型依赖不会被触发导入；同时它比运行时内省更好地保留注释、Markdown 风格的 docstring 与签名中的 TypedDict。

本地开发：三步跑起来

README 给出了完整的本地运行流程，全部在apps/site目录下执行：

cd apps/site npm install npm run sync # generate API tree + import release notes / changelog npm run dev # http://localhost:3001

需要说明的是，package.json中dev脚本实际指定的是next dev --port 3021，README 中的 3001 与 package.json 的 3021 存在不一致——以 apps/site/package.json 的实际端口 3021 为准（README 示例仅供理解流程）。npm run sync对应node scripts/sync-content.mjs，它会在开发前把 API 树、发布说明、变更日志一次性同步到content/下。

sync-content.mjs到底做了什么

apps/site/scripts/sync-content.mjs 是内容管线的枢纽，按顺序执行三件事，且幂等——每次运行都从零重建输出文件，可安全重复执行：

1. 生成 API 树：通过execSync调用uv run --with griffe python scripts/gen_api_tree.py生成content/api-tree.json。若 griffe 提取失败（例如在只有站点源码、没有引擎源码的部署预览环境中），脚本会降级写入空树{}，保证构建不中断，此时/reference页面将使用过期或空的树。
2. 导入发布说明为博客文章：读取仓库根 docs/revamp/release_notes_pycaret4.md，按# Session NN — DATE — TITLE标题切块，每个块生成一篇content/blog/session-NN.mdx。同步前会先删除旧的session-*.mdx，避免堆积过期文章。
3. 同步变更日志：把仓库根 CHANGELOG.md 复制为content/changelog.md，供/changelog路由渲染。

构建与静态导出

npm run build # static export to ./out

构建由package.json中的build脚本定义：node scripts/sync-content.mjs && next build，即构建前总是先同步内容，保证 API 树与发布说明是最新的。next.config.mjs 中设置了output: 'export'、trailingSlash: true、images.unoptimized: true，产物是一份完全静态的站点，因此可以部署到任意 CDN——GitHub Pages、Vercel、Cloudflare Pages 均可，这也是 README 声称「切换到 Vercel / Cloudflare Pages 只需改一行 workflow」的原因。

仓库根 .github/workflows/site.yml 印证了 CI 流程：每次推送到main（且改动命中apps/site/**、packages/engine/pycaret/**、docs/revamp/release_notes_pycaret4.md、CHANGELOG.md或 workflow 自身时）触发构建；在 Node 22 + Python 3.13 环境中依次执行 npm 依赖安装、griffe 生成 API 树、同步内容、TypeScript 类型检查、next build，最后用actions/upload-pages-artifact@v3上传apps/site/out，再由actions/deploy-pages@v4发布到 GitHub Pages。workflow_dispatch允许手动触发。

内容管理：四类内容的正确维护姿势

README 与 apps/site/AGENTS.md 共同定义了内容维护规则，核心原则是手写内容放进content/，自动生成的内容绝不手改。

新增文档页（Docs）

向content/docs/<section>/<slug>.mdx放置一个带 front-matter 的 MDX 文件即可，例如：

--- title: "Tuning hyperparameters" description: "How tune_model works in PyCaret 4.0." section: "Guides" order: 3 --- # body in markdown / MDX

• section决定侧边栏分组，稳定分组为Getting started、Concepts、Preprocessing、Functions、Guides、Resources，其余值归入「Other」（分组排序逻辑见 apps/site/lib/content.ts 的buildDocsSidebar）；
• order控制组内排序（小的在前），未提供时默认 99；
• 路由自动生成：/docs/<section-folder>/<slug>/，由 app/docs/[[...slug]]/page.tsx 的generateStaticParams在构建期枚举所有条目，配合静态导出友好。

前端加载器 apps/site/lib/content.ts 用gray-matter解析 front-matter，递归遍历content/docs与content/blog，并把条目按 section + order 排序后交给侧边栏与页面路由。

新增博客文章（Blog）

有两条路径：

1. 自动导入：docs/revamp/release_notes_pycaret4.md是唯一权威来源，每个# Session NN — DATE — TITLE块成为一篇博客，追加新 session 后下一次 CI 构建即发布。
2. 手写：向content/blog/<slug>.mdx放置带date: "YYYY-MM-DD"字段的 MDX，博客索引按日期降序排列。

更新 API 参考（Reference）——不要手改

API 参考完全自动生成。scripts/gen_api_tree.py 通过 griffe 遍历pycaret包的公开面，过滤掉下划线私密名称后输出content/api-tree.json。本地重新生成：

cd apps/site npm run gen:api

脚本中PUBLIC_ROOTS列表定义了纳入参考的公开模块（pycaret.classification、pycaret.regression、pycaret.plots.*、pycaret.logging.events等），如果某个公开符号出现在错误的分类中，就调整这个列表。渲染端 apps/site/lib/api-tree.ts 提供类型化访问器（模块/类/函数/参数/属性），app/reference/[...slug]/page.tsx 把 slug 拼回pycaret.<...>限定名并渲染出 Class / Function / Attribute 卡片。

一个值得一提的实现细节：Python docstring 是 RST 风格（Sphinx/Napoleon），Docstring.tsx 会做三件事把它转换为 Markdown——4 空格缩进块转```python代码围栏、RST 双反引号转 Markdown 单反引号、Sphinx:param:/:returns:/:raises:字段转粗体前缀行，然后复用同一套MdxRenderer渲染，保证风格统一。

更新变更日志（Changelog）

/changelog路由读取apps/site/content/changelog.md，它是仓库根 CHANGELOG.md 的镜像（由sync-content.mjs同步）。只需修改仓库根的CHANGELOG.md，下一次 CI 构建就会自动带到站点上。

目录结构与数据流全景

apps/site/AGENTS.md 给出了完整的目录地图，整理如下：

apps/site/ ├── app/ # Next.js 15 App Router 路由 │ ├── page.tsx # 落地页（Hero / 特性 / CTA） │ ├── docs/ # 手写指南与教程（MDX） │ ├── reference/ # 自动生成的 API 参考（来自 griffe） │ ├── blog/ # 博客（手写 + 自动导入） │ └── changelog/ # 仓库根 CHANGELOG.md 的镜像 ├── components/ # React 组件（MDX 渲染器、页头、页脚、侧边栏等） ├── content/ # 页面内容（Agent 唯一应编辑内容的目录） │ ├── docs/<section>/<page>.mdx │ ├── blog/<slug>.mdx │ ├── changelog.md # 自动导入，勿手改 │ └── api-tree.json # 自动生成，勿手改 ├── lib/ # 内容与 API 树加载器（TypeScript） ├── public/ # 静态资源（favicon、og:image 等） ├── scripts/ │ ├── gen_api_tree.py # Python：griffe → content/api-tree.json │ └── sync-content.mjs # Node：导入发布说明 + 变更日志 └── package.json

由此可以勾勒出完整的数据流：源码（packages/engine/pycaret/**）→ griffe 静态分析 →content/api-tree.json→/reference页面；发布说明（docs/revamp/release_notes_pycaret4.md）→ sync 脚本 →content/blog/session-*.mdx→/blog；根CHANGELOG.md→ sync 脚本 →content/changelog.md→/changelog；手写 MDX →content/docs/→/docs。站点是纯静态导出，引擎只会在构建期运行于 griffe 提取器内部，绝不会被直接 import 进站点。

新增站点板块（Section）的标准流程

当需要添加比单页更大的板块（如/showcase画廊或/community页面）时，README/AGENTS 给出了四步流程：

1. 在app/<section>/page.tsx添加路由文件；
2. 在 components/SiteHeader.tsx 的NAV常量中添加导航链接；
3. 在 components/SiteFooter.tsx 的COLUMNS常量中添加页脚链接；
4. 若该板块需要自己的侧边栏导航，参考 app/docs/layout.tsx 的模式——服务端构建侧边栏，客户端仅做当前链接高亮（见 DocsSidebar.tsx，用usePathname计算激活项）。

维护约定：给内容贡献者与 Agent 的规范

apps/site/AGENTS.md 明确写明了面向 AI Agent（Claude、Cursor、Copilot 等）的维护约定，核心条目如下：

• 语气：简洁、技术化、不夸大，与其余文档保持一致；
• 代码示例必须可原样运行：一律导入公开 API（如from pycaret.classification import ClassificationExperiment），绝不导入内部模块；
• 与 3.x 的差异：文档化某个功能时，若迁移会让老用户意外，需说明与 3.x 的不同；
• 绘图示例：始终使用pycaret.plots.<task>.<kind>，绝不调用已删除的plot_model；
• 不用 emoji（除非用户明确要求）；
• 字体：仅使用 Inter 与 JetBrains Mono，由 Tailwind 配置经 Google Fonts 引入（见 tailwind.config.ts）；
• 不要做的三件事：不要手写/编辑content/api-tree.json（每次构建重新生成）、不要手写/编辑content/changelog.md（从仓库根同步）、不要编辑自动导入的博客content/blog/session-*.mdx（由发布说明重新生成）、不要直接把引擎 import 进站点。

落地页与内容示例

作为「锦上添花」的参考，app/page.tsx 展示了落地页的组成：Hero 区块、生态伙伴文字区、代码示例（一段 20 行内完成「取数 → 建立实验 → 对比 12 个模型 → 调参 → 固化部署」的完整 AutoML 循环）、六大特性网格（五任务统一 API、sklearn 原生、Plotly 原生诊断、生产就绪、工作区感知、精简依赖）、仪表盘预览与 CTA。

content/docs/下的真实文档（如 apps/site/content/docs/getting-started/quickstart.mdx）则演示了「文档页 + 返回类型表格 + 跨任务同一 API」的写作范式——每个动词返回一个 dataclass（CreateResult、CompareResult、TuneResult、FinalizeResult、PredictResult），.pipeline槽位永远是真实的sklearn.pipeline.Pipeline，可直接joblib.dump或挂载到 FastAPI 后面。新写的文档页若涉及 API，会自动出现在/reference中，与手写指南互相印证。

总结

apps/site是一个典型的「单应用多内容源」文档站样板：Next.js 15 静态导出保证部署可移植，next-mdx-remote-client+ Shiki 提供零运行时的 MDX 渲染，griffe 打通了「Python 源码 → JSON API 树 → 前端参考页」的自动生成链路，sync-content.mjs则把发布说明与变更日志变成 CI 驱动的自动内容流。无论你是想为 PyCaret 4.0 贡献一篇文档，还是在自己的项目里复刻这套「手写内容 + 自动同步」的文档工程实践，本文梳理的目录结构、脚本职责与维护约定都可以作为直接的施工蓝图。