尧图网页设计 
Zitadel 文档站点开发实战基于 Fumadocs、Nx 与 Next.js 的 docs 应用构建流程【免费下载链接】zitadelZITADEL - Identity infrastructure, simplified for you.项目地址: https://gitcode.com/GitHub_Trending/zi/zitadel本文以 Zitadel 仓库中apps/docs文档应用的官方说明 apps/docs/README.md 为主体结合 Nx 目标定义、MDX 源码配置 与各类校验脚本完整讲解如何本地启动文档站、各构建/校验脚本的作用、内容生成的完整依赖链以及新增文档页面、通过质量检查并规范提交 PR 的全套流程。读完你可以独立承担 Zitadel 文档站的开发与维护工作。一、技术栈概览Fumadocs Next.js Nx 的分工Zitadel 的文档站点是官方文档站技术选型在 apps/docs/README.md 与 apps/docs/AGENTS.md 中说明如下框架Fumadocs构建在 Next.js 之上。从 依赖清单 可确认具体版本next 16.2.11、react 19.2.6以及锁定版本的fumadocs-core 16.8.10、fumadocs-ui 16.8.10、fumadocs-mdx 14.3.2、fumadocs-openapi 10.8.2。内容格式MDXMarkdown React 组件内容全部位于apps/docs/content目录。编排工具Nx。所有开发任务统一通过pnpm nx run zitadel/docs:target调用各目标在 Nx 项目配置 中声明。API 文档生成仓库内还引入了scalar/api-reference与 Shiki 语法高亮shikijs/rehype用于渲染 OpenAPI 交互式参考与代码块。内容集合的定义在 source.config.ts 中。该文件声明了两个 MDX 集合// 最新未版本化文档 export const docs defineDocs({ dir: content, docs: { schema: frontmatterSchema.extend({ sidebar_label: z.string().optional(), // 允许自定义侧边栏显示名 }), files: [**/*.md, **/*.mdx, !v*/**/*, !**/_*], }, }); // 版本化文档content/v* 子目录 export const versions defineDocs({ dir: content, docs: { files: [v*/**/*.md, v*/**/*.mdx, !**/_*], }, meta: { files: [v*/meta.json, v*/**/meta.json] }, });从中可以读出三条约定版本化目录content下顶层的v*目录被docs集合排除、被versions集合纳入即“最新版本”与“历史版本”由两套独立的 Fumadocs 集合承载私有内容以_开头的文件如_partial.mdx被!**/_*排除对应后文风格指南中的嵌入内容约定frontmatter 校验title等字段由 Zod schemafrontmatterSchema强校验这也是check:links能报出“缺少必填 frontmatter”错误的底层原因。页面在运行时如何路由到对应集合见 lib/source.tsgetPage()会先判断首个 slug 是否以v开头若是则走versionSource否则走最新的source。二、本地开发环境搭建2.1 前置条件根仓库 Quick StartREADME 要求先完成根目录的 贡献指南 Quick Start其中与文档站相关的依赖为Node.js v22.xUI 开发与运行pnpm nx ...命令必需Go文档站生成 API 文档时会用到 Go 编写的 protoc 插件见 install-proto-plugins.sh需按go.mod声明的版本安装pnpm通过 Corepack 启用并锁定版本pnpm install安装全部工作区依赖仓库使用 pnpm workspace见 pnpm-workspace.yaml。2.2 启动开发服务器pnpm install # 确保所有依赖已安装 pnpm nx run zitadel/docs:dev # 启动开发服务器站点随后运行在http://localhost:3000。注意从 Nx 目标定义 看dev目标声明了dependsOn: [generate]即每次启动开发服务器前会先完整执行内容生成链见第四节首次启动因此会比较耗时。三、脚本一览与质量校验3.1 核心脚本表README 给出的文档工作流脚本如下对应 package.json 中的scripts字段与 Nx targets脚本说明dev启动开发服务器next dev自动依赖generatebuild构建生产应用next build自动依赖check-linksfetch:remote-content拉取远端 tag 与被引用的远程内容下载历史版本文档generate运行全部生成步骤fetch:remote-content、generate:proto-docs、generate:api-reference、generate:index-pagescheck:links校验内容完整性坏链、缺失 frontmatter、schema 错误check-types校验 TypeScript 类型fumadocs-mdx next typegen tsc --noEmittest运行全部校验步骤check-types、check:linkslint检查代码风格与语法错误ESLint覆盖 JS/TS/MDX 文件clean清理构建产物与生成文件3.2 代码质量与内容完整性校验代码质量pnpm nx run zitadel/docs:lint基于 ESLint flat config含eslint-plugin-mdx对 JS/TS/MDX 文件做风格与语法检查。内容完整性pnpm nx run zitadel/docs:check-links校验内容包括失效的内部链接broken internal links缺失的必填 front-matter例如title图片引用是否有效。check:links的实现在 scripts/check-links.ts它先注册fumadocs-mdx/node/loader以读取 MDX 源码把source.getPages()与versionSource.getPages()合并为全部页面再读取 redirects.json 中的重定向规则一并纳入扫描 URL最后用next-validate-link的validateFiles逐文件校验以/docs为 baseUrl。校验通过后还会把扫描到的全部 URL 写入scanned-urls.json供后续排查使用。四、构建过程generate背后的完整生成链README 说明文档构建过程通过generate自动完成四件事下载所需的 protoc 插件从 proto 文件生成 gRPC 文档从 OpenAPI 规范生成 API 文档为目录结构生成 index 文件。从 project.json 的目标依赖关系看实际的执行链比 README 的概述更细是一条带缓存的依赖图fetch-remote-content ──┐ ├── install-proto-plugins │ │ │ ▼ └── generate-proto-docs输出到 apps/docs/openapi │ ▼ generate-api-reference输出 content/reference/api 与各版本的 reference/api │ ▼ fix-api-links │ fix-api-links ── build-mdx-sourcefumadocs-mdx输出 .source──┐ generate-index-pages ─────────────────────────────────────────────┴── generate关键细节fetch-remote-contentscripts/fetch-remote-content.mjs通过git ls-remote取回最近 5 个版本 tagNx 用该 runtime 命令作为缓存输入判断下载对应历史版本的文档内容到content/v*与public/v*并生成content/versions.json——这正是 source.config.ts 中versions集合的数据来源install-proto-plugins执行 install-proto-plugins.sh把 Go 编写的protoc-gen-connect-openapi等插件安装到仓库根的.artifacts/bin/os/arch/generate-proto-docs目标会把这些目录临时加入PATH后再调用 generate-proto-docs.mjsgenerate-api-referencescripts/generate-api-reference.ts消费上一步产出的 OpenAPI 文件生成content/reference/api下的 MDX 页面fix-api-links则负责修复文档正文中指向 API 参考的旧链接generate-index-pagesscripts/generate-index-pages.ts为各目录生成index.mdx索引页输出路径为content/**/index.mdx除文档正文外还有一个独立的generate-error-reference目标scripts/generate-error-reference.ts其缓存输入覆盖internal/**/*.go、backend/**/*.go与各模块的i18n/en.yaml可见错误码参考页是直接从 Go 源码中的错误定义自动抽取的。这些生成物.source、openapi/、content/reference/api、content/v*、content/versions.json等均为 Git 忽略的本地文件因此贡献流程要求提交前先跑pnpm nx run zitadel/docs:generate根 CONTRIBUTING.md Quick Start 第 5 步为全仓pnpm nx run-many --target generate。五、新增文档内容的规范操作5.1 添加新页面仅接受.mdx全部文档内容位于content目录系统只接受.mdx文件source.config.ts的 files glob 虽兼容.md但贡献规范要求统一 MDX。新增页面的完整步骤在content的合适子目录下创建.mdx文件并写好 Fumadocs 标准 frontmattertitle、description可选sidebar_label将新页面注册到侧边栏配置lib/sidebar-data.ts使其在导航中可见。该文件定义了SidebarItem类型支持category分类目录、link外部链接、doc指定文档页、generated-index指向自动生成的索引页等条目类型例如 Key Concepts 分类就通过generated-index类型指向concepts索引页。5.2 风格约定Style GuideREADME 给出的书写规范与 Google Developer Style Guide 通用指南一致变量占位代码示例中尽量使用环境变量占位避免硬编码凭据嵌入内容被其他页面嵌入引用的内容使用_filename.mdx命名这类文件不单独进入索引对应 source.config.ts 中的!**/_*排除规则代码内嵌利用代码块中的file属性从仓库中嵌入真实代码保证示例与源码同步语气使用主动语态标题使用句首大写sentence case。5.3 PR 提交规范PR 标题格式docs(scope): short summary提交前必过质量检查pnpm nx run zitadel/docs:build从 Nx 配置 可知build目标dependsOn: [^build, check-links]即生产构建前会自动先跑内容完整性校验再执行next build而test目标则聚合check-types与check-links。另注意 AGENTS.md 提醒当proto/目录或 API 响应 schema 变更时通常需要重新运行文档生成目标以刷新 gRPC/OpenAPI 参考页。六、故障排查Nx 配置找不到的处理README 专门记录了两类高频启动失败及其统一解法。现象一找不到任务配置NX Cannot find configuration for task zitadel/zitadel:zitadel/docs:generate Pass --verbose to see the stacktrace.现象二nx命令本身不存在pnpm nx run zitadel/docs:dev ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL Command nx not found Did you mean pnpm nx?根因依赖缓存或node_modules与 lockfile 失同步out of sync。解决在仓库根目录按顺序执行清除 node_modulesrm -rf node_modules—— 删除已安装的依赖目录清除 pnpm 缓存pnpm cache delete—— 清空 pnpm 内部包缓存重新安装依赖pnpm install—— 全新安装所有依赖验证环境pnpm nx run zitadel/docs:generate—— 确认整套生成链可正常跑通。按 README 的说法该流程可解决绝大多数99%的环境搭建类问题。若命令因已有进程占用而卡住还可按根 CONTRIBUTING.md 的命令速查表停止 Nx daemon 重试pnpm nx daemon --stop。七、相关入口文件速查内容路径文档应用说明本文主体apps/docs/README.mdAI 协作规范已验证的 Nx 目标清单apps/docs/AGENTS.mdNx 目标与依赖图apps/docs/project.jsonMDX 集合 / 版本化 / 高亮配置apps/docs/source.config.ts运行时页面路由最新 vs 版本apps/docs/lib/source.ts侧边栏数据与条目类型apps/docs/lib/sidebar-data.ts链接/frontmatter/图片校验apps/docs/scripts/check-links.ts根仓库 Quick Start 与开发命令速查表CONTRIBUTING.md综上Zitadel 的文档站把“内容 → 生成 → 校验 → 构建”串成一条由 Nx 统一编排、带缓存的流水线开发侧只需记住generate、dev、build三个入口而内容规范仅 MDX、_前缀私有文件、侧边栏注册、frontmatter 强校验保证了文档结构与 API 参考页始终和源码保持同步。【免费下载链接】zitadelZITADEL - Identity infrastructure, simplified for you.项目地址: https://gitcode.com/GitHub_Trending/zi/zitadel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Zitadel 文档站点开发实战：基于 Fumadocs、Nx 与 Next.js 的 docs 应用构建流程
Zitadel 文档站点开发实战基于 Fumadocs、Nx 与 Next.js 的 docs 应用构建流程【免费下载链接】zitadelZITADEL - Identity infrastructure, simplified for you.项目地址: https://gitcode.com/GitHub_Trending/zi/zitadel本文以 Zitadel 仓库中apps/docs文档应用的官方说明 apps/docs/README.md 为主体结合 Nx 目标定义、MDX 源码配置 与各类校验脚本完整讲解如何本地启动文档站、各构建/校验脚本的作用、内容生成的完整依赖链以及新增文档页面、通过质量检查并规范提交 PR 的全套流程。读完你可以独立承担 Zitadel 文档站的开发与维护工作。一、技术栈概览Fumadocs Next.js Nx 的分工Zitadel 的文档站点是官方文档站技术选型在 apps/docs/README.md 与 apps/docs/AGENTS.md 中说明如下框架Fumadocs构建在 Next.js 之上。从 依赖清单 可确认具体版本next 16.2.11、react 19.2.6以及锁定版本的fumadocs-core 16.8.10、fumadocs-ui 16.8.10、fumadocs-mdx 14.3.2、fumadocs-openapi 10.8.2。内容格式MDXMarkdown React 组件内容全部位于apps/docs/content目录。编排工具Nx。所有开发任务统一通过pnpm nx run zitadel/docs:target调用各目标在 Nx 项目配置 中声明。API 文档生成仓库内还引入了scalar/api-reference与 Shiki 语法高亮shikijs/rehype用于渲染 OpenAPI 交互式参考与代码块。内容集合的定义在 source.config.ts 中。该文件声明了两个 MDX 集合// 最新未版本化文档 export const docs defineDocs({ dir: content, docs: { schema: frontmatterSchema.extend({ sidebar_label: z.string().optional(), // 允许自定义侧边栏显示名 }), files: [**/*.md, **/*.mdx, !v*/**/*, !**/_*], }, }); // 版本化文档content/v* 子目录 export const versions defineDocs({ dir: content, docs: { files: [v*/**/*.md, v*/**/*.mdx, !**/_*], }, meta: { files: [v*/meta.json, v*/**/meta.json] }, });从中可以读出三条约定版本化目录content下顶层的v*目录被docs集合排除、被versions集合纳入即“最新版本”与“历史版本”由两套独立的 Fumadocs 集合承载私有内容以_开头的文件如_partial.mdx被!**/_*排除对应后文风格指南中的嵌入内容约定frontmatter 校验title等字段由 Zod schemafrontmatterSchema强校验这也是check:links能报出“缺少必填 frontmatter”错误的底层原因。页面在运行时如何路由到对应集合见 lib/source.tsgetPage()会先判断首个 slug 是否以v开头若是则走versionSource否则走最新的source。二、本地开发环境搭建2.1 前置条件根仓库 Quick StartREADME 要求先完成根目录的 贡献指南 Quick Start其中与文档站相关的依赖为Node.js v22.xUI 开发与运行pnpm nx ...命令必需Go文档站生成 API 文档时会用到 Go 编写的 protoc 插件见 install-proto-plugins.sh需按go.mod声明的版本安装pnpm通过 Corepack 启用并锁定版本pnpm install安装全部工作区依赖仓库使用 pnpm workspace见 pnpm-workspace.yaml。2.2 启动开发服务器pnpm install # 确保所有依赖已安装 pnpm nx run zitadel/docs:dev # 启动开发服务器站点随后运行在http://localhost:3000。注意从 Nx 目标定义 看dev目标声明了dependsOn: [generate]即每次启动开发服务器前会先完整执行内容生成链见第四节首次启动因此会比较耗时。三、脚本一览与质量校验3.1 核心脚本表README 给出的文档工作流脚本如下对应 package.json 中的scripts字段与 Nx targets脚本说明dev启动开发服务器next dev自动依赖generatebuild构建生产应用next build自动依赖check-linksfetch:remote-content拉取远端 tag 与被引用的远程内容下载历史版本文档generate运行全部生成步骤fetch:remote-content、generate:proto-docs、generate:api-reference、generate:index-pagescheck:links校验内容完整性坏链、缺失 frontmatter、schema 错误check-types校验 TypeScript 类型fumadocs-mdx next typegen tsc --noEmittest运行全部校验步骤check-types、check:linkslint检查代码风格与语法错误ESLint覆盖 JS/TS/MDX 文件clean清理构建产物与生成文件3.2 代码质量与内容完整性校验代码质量pnpm nx run zitadel/docs:lint基于 ESLint flat config含eslint-plugin-mdx对 JS/TS/MDX 文件做风格与语法检查。内容完整性pnpm nx run zitadel/docs:check-links校验内容包括失效的内部链接broken internal links缺失的必填 front-matter例如title图片引用是否有效。check:links的实现在 scripts/check-links.ts它先注册fumadocs-mdx/node/loader以读取 MDX 源码把source.getPages()与versionSource.getPages()合并为全部页面再读取 redirects.json 中的重定向规则一并纳入扫描 URL最后用next-validate-link的validateFiles逐文件校验以/docs为 baseUrl。校验通过后还会把扫描到的全部 URL 写入scanned-urls.json供后续排查使用。四、构建过程generate背后的完整生成链README 说明文档构建过程通过generate自动完成四件事下载所需的 protoc 插件从 proto 文件生成 gRPC 文档从 OpenAPI 规范生成 API 文档为目录结构生成 index 文件。从 project.json 的目标依赖关系看实际的执行链比 README 的概述更细是一条带缓存的依赖图fetch-remote-content ──┐ ├── install-proto-plugins │ │ │ ▼ └── generate-proto-docs输出到 apps/docs/openapi │ ▼ generate-api-reference输出 content/reference/api 与各版本的 reference/api │ ▼ fix-api-links │ fix-api-links ── build-mdx-sourcefumadocs-mdx输出 .source──┐ generate-index-pages ─────────────────────────────────────────────┴── generate关键细节fetch-remote-contentscripts/fetch-remote-content.mjs通过git ls-remote取回最近 5 个版本 tagNx 用该 runtime 命令作为缓存输入判断下载对应历史版本的文档内容到content/v*与public/v*并生成content/versions.json——这正是 source.config.ts 中versions集合的数据来源install-proto-plugins执行 install-proto-plugins.sh把 Go 编写的protoc-gen-connect-openapi等插件安装到仓库根的.artifacts/bin/os/arch/generate-proto-docs目标会把这些目录临时加入PATH后再调用 generate-proto-docs.mjsgenerate-api-referencescripts/generate-api-reference.ts消费上一步产出的 OpenAPI 文件生成content/reference/api下的 MDX 页面fix-api-links则负责修复文档正文中指向 API 参考的旧链接generate-index-pagesscripts/generate-index-pages.ts为各目录生成index.mdx索引页输出路径为content/**/index.mdx除文档正文外还有一个独立的generate-error-reference目标scripts/generate-error-reference.ts其缓存输入覆盖internal/**/*.go、backend/**/*.go与各模块的i18n/en.yaml可见错误码参考页是直接从 Go 源码中的错误定义自动抽取的。这些生成物.source、openapi/、content/reference/api、content/v*、content/versions.json等均为 Git 忽略的本地文件因此贡献流程要求提交前先跑pnpm nx run zitadel/docs:generate根 CONTRIBUTING.md Quick Start 第 5 步为全仓pnpm nx run-many --target generate。五、新增文档内容的规范操作5.1 添加新页面仅接受.mdx全部文档内容位于content目录系统只接受.mdx文件source.config.ts的 files glob 虽兼容.md但贡献规范要求统一 MDX。新增页面的完整步骤在content的合适子目录下创建.mdx文件并写好 Fumadocs 标准 frontmattertitle、description可选sidebar_label将新页面注册到侧边栏配置lib/sidebar-data.ts使其在导航中可见。该文件定义了SidebarItem类型支持category分类目录、link外部链接、doc指定文档页、generated-index指向自动生成的索引页等条目类型例如 Key Concepts 分类就通过generated-index类型指向concepts索引页。5.2 风格约定Style GuideREADME 给出的书写规范与 Google Developer Style Guide 通用指南一致变量占位代码示例中尽量使用环境变量占位避免硬编码凭据嵌入内容被其他页面嵌入引用的内容使用_filename.mdx命名这类文件不单独进入索引对应 source.config.ts 中的!**/_*排除规则代码内嵌利用代码块中的file属性从仓库中嵌入真实代码保证示例与源码同步语气使用主动语态标题使用句首大写sentence case。5.3 PR 提交规范PR 标题格式docs(scope): short summary提交前必过质量检查pnpm nx run zitadel/docs:build从 Nx 配置 可知build目标dependsOn: [^build, check-links]即生产构建前会自动先跑内容完整性校验再执行next build而test目标则聚合check-types与check-links。另注意 AGENTS.md 提醒当proto/目录或 API 响应 schema 变更时通常需要重新运行文档生成目标以刷新 gRPC/OpenAPI 参考页。六、故障排查Nx 配置找不到的处理README 专门记录了两类高频启动失败及其统一解法。现象一找不到任务配置NX Cannot find configuration for task zitadel/zitadel:zitadel/docs:generate Pass --verbose to see the stacktrace.现象二nx命令本身不存在pnpm nx run zitadel/docs:dev ERR_PNPM_RECURSIVE_EXEC_FIRST_FAIL Command nx not found Did you mean pnpm nx?根因依赖缓存或node_modules与 lockfile 失同步out of sync。解决在仓库根目录按顺序执行清除 node_modulesrm -rf node_modules—— 删除已安装的依赖目录清除 pnpm 缓存pnpm cache delete—— 清空 pnpm 内部包缓存重新安装依赖pnpm install—— 全新安装所有依赖验证环境pnpm nx run zitadel/docs:generate—— 确认整套生成链可正常跑通。按 README 的说法该流程可解决绝大多数99%的环境搭建类问题。若命令因已有进程占用而卡住还可按根 CONTRIBUTING.md 的命令速查表停止 Nx daemon 重试pnpm nx daemon --stop。七、相关入口文件速查内容路径文档应用说明本文主体apps/docs/README.mdAI 协作规范已验证的 Nx 目标清单apps/docs/AGENTS.mdNx 目标与依赖图apps/docs/project.jsonMDX 集合 / 版本化 / 高亮配置apps/docs/source.config.ts运行时页面路由最新 vs 版本apps/docs/lib/source.ts侧边栏数据与条目类型apps/docs/lib/sidebar-data.ts链接/frontmatter/图片校验apps/docs/scripts/check-links.ts根仓库 Quick Start 与开发命令速查表CONTRIBUTING.md综上Zitadel 的文档站把“内容 → 生成 → 校验 → 构建”串成一条由 Nx 统一编排、带缓存的流水线开发侧只需记住generate、dev、build三个入口而内容规范仅 MDX、_前缀私有文件、侧边栏注册、frontmatter 强校验保证了文档结构与 API 参考页始终和源码保持同步。【免费下载链接】zitadelZITADEL - Identity infrastructure, simplified for you.项目地址: https://gitcode.com/GitHub_Trending/zi/zitadel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考