用途:维护 NeMo Gym 的 Fern 文档站点,统一处理在 fern/ 下新增、更新、移动、删除页面的操作,包括发布说明与迁移指南。所有文档编辑都发生在 fern/ 下。
版本结构:fern/versions/latest/ 是持续更新的前沿内容树,通过 main.yml 挂载到 main 主 slug;每个已发布版本保留冻结的 GA 快照(当前为 v0.2.1)。新编辑默认只落在 latest/,只有用户明确要求才回移到 GA 快照。latest.yml 是指向当前 GA yml 的符号链接,使 /latest/... 与 /<current-ga>/... 提供相同页面。
主要操作:新增页面时在 fern/versions/latest/pages/<子目录>/ 创建 kebab-case 的 .mdx,带 title、description、可选 position 前置字段;若父目录在 main.yml 中使用 title-source: frontmatter 则自动发现,否则需在 main.yml 加 - page: 条目。更新页面只改 MDX 内容;改名会导致 URL 变化,需在 fern/docs.yml 加 redirects。删除页面要先用 grep 查找入站链接、git rm、清理导航条目并修复链接,公开 URL 需加重定向。
内容规范:使用 Fern 原生 MDX 组件(Note、Tip、Info、Warning、Error、Cards、Card、Badge),不要用 GitHub 的 > [!NOTE] 语法。索引页用 Cards 网格,Badge 放 Card 末尾且不加内联样式。正文首行用 # 标题与 frontmatter 一致。图片放在 fern/assets/ 或版本 pages/ 下,用根相对路径引用。
校验与预览:首次需通过 npx -y fern-api@latest login 用 NVIDIA Google 账号登录。在 fern/ 下运行 npm run check 校验 YAML 与 frontmatter,npm run dev 在 localhost:3000 热重载预览;npm run generate:library 重新生成库参考。fern check 必须通过才能提交。dev 对 /latest/... 跨版本链接的断链警告是误报。
提交与发布:提交信息格式为 docs: <add|update|remove> <page-title>;涉及 fern/ 的 PR 会自动生成 Fern 预览 URL。推送到 main(改动 docs/ 或 fern/)、推送 docs/v* 标签或手动触发都会发布到 docs.nvidia.com/nemo/gym,标签格式为 docs/v<MAJOR>.<MINOR>.<PATCH>,不要未经用户要求推标签。
新版本火车:复制 latest 为 vX.Y.Z 快照、复制并改写 main.yml 为版本 yml、重定向 latest.yml 符号链接、在 docs.yml 中添加新 GA 条目并处理旧快照。
限制:回移到冻结 GA 快照需明确指令;本地校验器无法解析 docs.yml 中的版本 slug,跨版本链接警告为误报;预览评论与发布任务需要 DOCS_FERN_TOKEN 密钥。