authentik Docusaurus 多站点文档架构全解一个仓库如何搭出 3 个文档站指南【免费下载链接】authentikThe authentication glue you need.项目地址: https://gitcode.com/GitHub_Trending/au/authentik使用 authentik 文档时你会发现用户指南、第三方集成教程和 API 参考是 3 个互不相干的站点。其实这 3 个站点都维护在同一个仓库的website/目录里基于同一套 Docusaurus一个基于 React 的静态文档站点生成器构建。读完本文你能看懂它的多站点工作区结构、配置组装方式并用两条命令在本地跑起 authentik 文档的完整构建。 一个仓库三个文档站authentik 的文档不是单一站点而是按读者类型拆成的 3 个独立 Docusaurus 实例站点目录内容用户指南website/docs/安装配置、Flows 编排、用户与访问源、安全公告等 13 个主题目录集成教程website/integrations/200 多个 mdx 页面的第三方服务接入指南API 参考website/api/由根目录 OpenAPI 模式文件 自动生成的接口文档3 个站点通过 pnpm workspace把多个包装进同一个node_modules的管理方式挂在 website 根工作区 下共享依赖只需安装一次。workspace 结构图对这套布局有官方说明。⚙️ 核心机制配置文件如何组装站点单一入口三个同构的配置每个站点都有一个docusaurus.config.esm.mjs入口是同一个函数createDocusaurusConfig。以 docs 站点配置 为例它做了四件事用createClassicPreset预设开启文档路由routeBasePath直接挂在站点根路径/声明两个主题自定义主题goauthentik/docusaurus-theme加上官方的docusaurus/theme-mermaidMermaid 图渲染支持注册 3 个插件releases 版本发布插件、llms-txt 插件生成供大模型阅读的 llms.txt 目录页、redirects 旧链接重定向插件构建前把goauthentik/brand-assets里的品牌图标、社交分享卡复制到static/目录两个共享包定制逻辑不写在站点里而是拆进两个包包位置职责goauthentik/docusaurus-configpackages/docusaurus-config/配置工厂函数、3 个站点的 URL 常量goauthentik/docusaurus-themewebsite/docusaurus-theme/自定义主题、CSS、mermaid 图标、重定向/发布/llms.txt 插件、Algolia 搜索配置这样 3 个站点换主题、加插件时只改一处不会出现三份漂移的配置。侧边栏与自动分组用户指南的导航树由 sidebar.mjs 定义配合categories.mjs组织 13 个主题目录install-config、add-secure-apps、users-sources、developer-docs 等。其中有一段值得注意的自动逻辑security/cves下的安全公告页会被generateCVESidebar按标题里的年份自动分组、倒序排列新增 CVE 页面无需手动维护导航。️ 本地构建与预览 authentik 文档环境与安装workspace 清单 声明了硬性要求Node.js ≥ 24、pnpm ≥ 11.20.0。安装依赖用仓库 Makefile 封装的一条命令即可git clone https://gitcode.com/GitHub_Trending/au/authentik make docs-install常用命令pnpm --filter ./docs run start # 启动用户指南的开发预览 pnpm --filter ./docs run build # 构建用户指南产物在 website/build/ pnpm build / pnpm build:api / pnpm build:integrations # 在 website/ 下分别构建 3 个站点docs 站点的 build 脚本在docusaurus build之后还会把产物复制到website/build/三个站点共用同一个部署目录。官方开发环境搭建含 IDE 调试配置在 developer-docs 中有专门章节。 延伸阅读与贡献路径想改一个文档页面路径很直接找到目标站点目录website/docs/、website/integrations/或website/api/下的 mdx 文件用上面的命令本地预览确认无误向仓库提交 Pull Request关键文件速查website/README.mdworkspace 结构与包关系总览website/docs/sidebar.mjs侧边栏与自动分组规则website/docusaurus-theme/自定义主题与插件源码website/docs/developer-docs/写作规范、样式指南与贡献流程schema.ymlAPI 文档的生成源接口变更会同步反映到 API 站生产部署由 Netlify 加仓库 CI 工作流完成每个站点目录下的netlify.toml描述了各自的构建配置。如果你改过其中任何一个 mdx 文件本地跑一次pnpm --filter ./docs run build就是完整的自检流程。【免费下载链接】authentikThe authentication glue you need.项目地址: https://gitcode.com/GitHub_Trending/au/authentik创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考