authentik文档系统快速上手3个问题看懂Docusaurus构建链路【免费下载链接】authentikThe authentication glue you need.项目地址: https://gitcode.com/GitHub_Trending/au/authentik打开 authentik 的文档站它看起来不过是一堆 Markdown 加套模板可你真去改的时候会发现构建链路比想象中绕得多为什么改了文档不生效、左侧目录谁在管、一个仓库凭什么拆出三个独立站点。这篇文章按三个新人最常问的问题展开带你摸清这套 Docusaurus 文档系统的实际构造。第一个问题改了文档为什么没立刻生效这是把静态站点当成内容管理服务时的经典误会。authentik 的文档不是存稿即发布每一页都要在构建时编译成静态 HTML。入口在 website/docs/配置文件 docusaurus.config.esm.mjs 用一次createDocusaurusConfig调用把全部设定拼好用哪个预设、挂哪些插件、套哪套主题都是在那一个地方合并完成的。所以改完 md 文件必须重新构建。在仓库根目录执行make docs会依次跑格式检查、拼写检查再编译开发时也可以直接起本地 dev server边写边热更新。最终产物落在 build/ 目录线上部署的就是这批静态文件。 换句话说改完没生效先确认自己构建过没有。第二个问题左侧目录骨架是谁定的侧边栏并不是手写的。配置指向本地的 sidebar.mjs 声明分类结构其余目录树由 Docusaurus 按文件系统自动生成。翻一下 docs 目录顶层就能看到对应关系install-config 是安装配置、users-sources 是用户与源管理、sys-mgmt 是系统管理——目录名即栏目名侧边栏只是把它们排好序。有意思的是例外配置文件里覆写了侧边栏生成逻辑一旦路径落在 security/cves就换成专门函数把所有 CVE 条目按年份归组、从新到旧排序。发一份漏洞公告不用人肉挪文章。这种自动生成 局部人工干预的模式是站点在几百篇规模下还能维持可读的关键。内容本身也是以大量分步截图为主比如这张流程创建界面第三个问题为什么一个仓库拆出三个站本地开发起来其实是三个站docs、integrations 和 api分别占 3000、3001、3002 端口。这个拆分定义在共享配置包 packages/docusaurus-config/ 里路由模块按本地和生产两套环境各记一份域名。website/integrations/ 下的第三方集成指南则是独立的一个 Docusaurus 实例——集成目录体量很大拆出去之后各站的构建和搜索索引都更轻。还有个容易被忽略的细节配置里挂了一个 remark 插件正文里以 /api 开头的绝对路径会被自动改写成 API 站的外链/integrations 则指回集成站。所以读文档时跳去了别的站不是 bug是设计好的。 再补一个较新的小动作配置里注入了 llms.txt 生成器按 topics.mjs 定义的栏目标题整理文档目录专门给大模型读。文档站开始服务的不只是人。文档描述的对象本身也在这个仓库里完整链路一张图收束踩坑排查速查症状先看哪里改了 md站点还是旧内容构建是否跑完或 dev server 是否还活着正文链接跳去了错误的站/api 与 /integrations 两条改写规则侧边栏层级不对sidebar.mjs 里的分类声明和目录命名新文章搜不到是否被配置里的 exclude 排除是否已进索引下一步可以动手试的3件事把代码拉到本地git clone https://gitcode.com/GitHub_Trending/au/authentik在仓库根目录跑一遍 docs 构建目标然后起 dev server浏览器打开本地 3000 端口挑一篇 md 加一行新内容触发重新构建看变化出现在页面上——这是把整条链路记进脑子里最快的方式【免费下载链接】authentikThe authentication glue you need.项目地址: https://gitcode.com/GitHub_Trending/au/authentik创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考