三个站点，一次构建：拆解 authentik 的 Docusaurus 文档系统
【免费下载链接】authentikThe authentication glue you need.项目地址: https://gitcode.com/GitHub_Trending/au/authentik
authentik 是一个开源身份提供商（IdP，负责用户认证与登录流程编排）。它的文档系统基于 Docusaurus 构建——你可以把 Docusaurus 理解为"把 Markdown 变成可部署网站"的静态站点生成器。读完这篇，你会知道：文档内容放在哪、配置文件管了什么、改了之后怎么变成线上页面。
文档放在哪：website 目录下的三个独立站点
文档系统不是一个站。website/ 下并行放着三套 Docusaurus 站点：docs（主站，安装与功能指南）、api（API 参考）、integrations（第三方集成教程）。三者各有独立的docusaurus.config.esm.mjs，各自构建、各自部署。
主站的内容目录按主题划分：
新增一篇内容，先归入这些目录之一，侧边栏位置就定了一半。
配置文件怎么驱动站点：预设加定制
站点配置入口是 docusaurus.config.esm.mjs。它不是一堆样板参数，而是先调用共享包@goauthentik/docusaurus-config里的createDocusaurusConfig统一基础设置，再用extendConfig叠加站点差异：
createClassicPreset开启文档预设（Preset 是 Docusaurus 内置的"文档+博客"标准能力包），并通过routeBasePath让 docs 内容挂在站点根路径- 侧边栏不在配置里手写，交给同目录的
sidebar.mjs按目录结构自动生成，只有security/cves这类目录做了特殊处理——按年份分组倒序展示 - 插件层挂了三样东西：releases 插件处理版本化文档、
llms.txt生成插件让大模型能抓取文档、link rewrite 插件把正文里的/api链接自动指向独立的 API 站点
主题方面，配置声明了@goauthentik/docusaurus-theme，导航栏、Algolia 搜索、样式统一收在 website/docusaurus-theme/ 里，三站共用。
写新文档要动哪些文件
那加一篇文档具体做什么？在对应主题目录丢一个.mdx文件，front matter 控制排序与分组，侧边栏自动生成，不用手动登记。图片放正文同级的子目录里，文字和截图就近存放。下面这张管理员界面截图就是文档配图风格的例子：
给文档加一种语言要几步
先澄清一个常见误解：仓库根目录 locale/ 下的 18 种语言，是前端管理界面的 gettext PO 文件，走 Django 编译，跟 Docusaurus 文档站没有关系。文档站点目前只发布英文。
若要给文档加语言，Docusaurus 提供标准 i18n 流程，大致四步：
- 在站点目录建
i18n/目录，配置里声明locales与defaultLocale - 运行
pnpm docusaurus write-translations --locale de提取待翻译字符串 - 在生成的目录里补全各语言文案
- 重新构建，产物会按语言前缀分目录输出
构建与发布：三站合成一个 build
发布链路收口在 website/package.json：build、build:api、build:integrations三个入口各自pnpm --filter一个子站点。关键在于每个站点的 build 脚本结尾都有cp -r ./build/ ../build/——三站的静态产物最终合并进同一个website/build/目录，部署时一套目录即可按子域分开服务。
CI 环境用 Docker 构建：pnpm 基础镜像负责依赖，Node 镜像执行构建，见 website/Dockerfile。主站目录下还有一份netlify.toml，说明静态托管也是被支持的发布方式之一。
延伸资源
- 主站配置入口：docusaurus.config.esm.mjs
- 侧边栏自动生成逻辑：sidebar.mjs
- 三站共享的 Docusaurus 配置包：packages/docusaurus-config/
- 文档内容批量管理工具（docsmg，Rust 编写）：scripts/docsmg/
【免费下载链接】authentikThe authentication glue you need.项目地址: https://gitcode.com/GitHub_Trending/au/authentik
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
