Strapi 贡献者文档站本地运行与构建：Docusaurus 配置、TypeDoc 集成与部署细节

Strapi 贡献者文档站本地运行与构建：Docusaurus 配置、TypeDoc 集成与部署细节

【免费下载链接】strapi🚀 Strapi is the leading open-source headless CMS. It’s 100% JavaScript/TypeScript, fully customizable, and developer-first.项目地址: https://gitcode.com/GitHub_Trending/st/strapi

本文基于 Strapi 仓库中docs/目录的贡献者文档说明（README），讲清如何在本地完成该文档站的安装、开发、构建全流程，并结合 docusaurus.config.ts、sidebars.ts 等配置文件深入解析其技术栈组成：Docusaurus 3.x、TypeDoc 自动生成 API 文档、本地搜索与 Mermaid 图支持的集成方式。读完后可独立跑起contributor.strapi.io对应的本地站点，并理解各配置项的实际作用。

这份文档站是给谁看的

需要先区分两个文档体系：面向最终用户的官方文档发布在 docs.strapi.io，而仓库docs/目录下维护的是贡献者文档（contributor documentation），专门面向希望为 Strapi 源码做贡献的工程师，解释内部技术概念、hooks、工具函数等内容。站点线上地址为 contributor.strapi.io，仓库内通过 docs/docs/index.md 进一步说明了其四大板块结构：

• Guides：贡献指南、行为准则，以及如“Working with the Design System”等日常开发指南；
• Docs：深入 monorepo 特定模块的技术与概念文档，例如数据库关系排序、useDragAndDrop等 hook 的使用文档；
• API Reference：对核心类的深入方法/参数说明；
• RFCs：已批准设计提案的记录，解释功能设计上的“为什么”。

对应地，sidebars.ts 定义了与这五大板块一一呼应的侧边栏，全部由文件系统自动推导（autogenerated）：

const sidebars: SidebarsConfig = { docs: [{ type: 'autogenerated', dirName: 'docs' }], api: [{ type: 'autogenerated', dirName: 'api' }], exports: [{ type: 'autogenerated', dirName: 'exports' }], guides: [{ type: 'autogenerated', dirName: 'guides' }], rfcs: [{ type: 'autogenerated', dirName: 'rfcs' }], };

注意这里引用的docs/、api/、guides/、rfcs/均相对于 Docusaurus 的 docs 根目录（即仓库的docs/docs/子目录），其中exports板块是构建期由 TypeDoc 动态生成的（见下文）。

安装依赖

文档站的依赖独立于主 monorepo 声明，入口说明为：

$ yarn install

在docs/目录下执行即可。依赖清单见 package.json，核心为：

resolutions字段额外锁定了@babel/*（7.29.7）等传递依赖版本，避免 Docusaurus 与 monorepo 根工作区之间的依赖冲突。

本地开发：yarn start

$ yarn start

启动本地开发服务器并自动打开浏览器窗口，文档修改大多可热更新、无需重启。对照 package.json 的 scripts 可以看到，start实际是：

"start": "TYPEDOC_WATCH=true docusaurus start"

TYPEDOC_WATCH=true这一环境变量并非装饰——docusaurus.config.ts 中 TypeDoc 插件的watch选项正是读取它：

const pluginTypedocOptions: Parameters<typeof TypedocPlugin>[1] = { entryPoints: ['../packages/core/strapi/src/admin.ts'], tsconfig: '../packages/core/strapi/tsconfig.build.json', readme: 'none', entryFileName: 'modules.md', out: 'docs/exports', watch: !!process.env.TYPEDOC_WATCH, };

含义是：开发模式下，当packages/core/strapi/src/admin.ts所代表的入口模块源码变化时，TypeDoc 会重新生成docs/exports下的 API 页面并触发站点刷新。配置内还留有两条值得注意的注释级“坑位”说明：

• readme: 'none'配合entryFileName: 'modules.md'是为了避免生成index.md（其中裸<br>标签不是合法 MDX）；且绝不能把entryFileName设为null，否则会退化为空 URL 并导致EISDIR写目录错误；
• docusaurus-plugin-typedocv1 的out目录直接写入指定路径，v0 会额外加 docs 根前缀，因此out必须写成docs/exports才能被 Docusaurus 作为内容目录拾取。

TypeDoc 的入口 admin.ts 与 tsconfig.build.json 均为真实存在的源码/构建配置，说明“Exports”板块的文档是直接从@strapi/core的公共 API 表面生成的，而非手写。

构建静态产物：yarn build

$ yarn build

执行docusaurus build，将全部页面生成静态内容输出到build/目录，之后可托管在任意静态内容服务上。构建期的完整管线包括：

1. 解析docs/docs/下的guides、docs、api、rfcs四个内容目录及index.md首页；
2. 运行 TypeDoc 插件，把admin.ts入口的导出渲染为docs/exports（被.gitignore明确列为生成物：/build、.docusaurus、/docs/exports均不入库）；
3. 本地搜索插件建立索引（indexBlog: false，且博客整体关闭，blog: false）；
4. 经自定义 remark 插件与 Mermaid 主题处理 Markdown 后输出静态文件。

package.json 中还提供了完整脚本集，可按需使用：

yarn serve # 本地预览 build 产物（docusaurus serve） yarn deploy # 部署（docusaurus deploy） yarn clear # 清理 .docusaurus 缓存 yarn swizzle # 主题组件定制脚手架 yarn write-heading-ids / yarn write-translations # MDX 锚点/翻译辅助

站点行为的关键配置

以下配置来自 docusaurus.config.ts，决定了站点的运行行为与内容规则：

路由与内容规则

• routeBasePath: '/'：文档直接挂在站点根路径（而非默认的/docs），因此页面形如contributor.strapi.io/guides/...、/docs/core/...，与 docs/docs/index.md 中的内部链接保持一致；
• trailingSlash: false：URL 统一不带尾斜杠；
• onBrokenLinks: 'warn'与markdown.hooks.onBrokenMarkdownLinks: 'warn'：坏链只告警不中断构建，配合markdown.mermaid: true允许在 MDX 中嵌入流程图。

React 解析别名插件

配置中注册了一个内联插件resolve-react（plugins），通过 webpack alias 强制react解析到docs/node_modules/react。从源码结构看，这是 monorepo 工作区下的典型防御：若 Docusaurus 构建时意外解析到根node_modules中的另一份 React，会造成重复实例与 hooks 报错，别名确保站点内部只有一份 React 18.3.1。

设计系统链接重写插件

remark-design-system-links.ts 是一个自定义 remark 转换器，作为docs.remarkPlugins之一注册。它解决的问题是：TypeDoc 从@strapi/design-system的.d.ts文件提取 JSDoc 时，注释里包含指向 Storybook 的相对路径链接（如Label），这类 URL 在 Docusaurus 中会被当作站内相对链接解析并触发坏链检查。该插件遍历 MDAST 树中的link与html节点，把../?path=/..?path=前缀统一改写为设计系统公共站点（design-system.strapi.io）的绝对地址，保证生成文档中的链接可直接跳转。

Mermaid 与搜索

• themes: ['@docusaurus/theme-mermaid']+markdown.mermaid: true：文档正文（例如 docs/docs/docs 中的架构说明）可直接使用 Mermaid 代码块绘制图表；
• @cmfcmf/docusaurus-search-local：构建期建立本地倒排索引，前端提供开箱即用的全文搜索，无第三方索引依赖。

面向 Vercel 的增量构建优化

vercel.json 只有一条规则，却体现了文档站与主仓库的耦合面控制：

{ "ignoreCommand": "git diff HEAD^ HEAD --quiet -- . ../packages/core/strapi/ && exit 0 || exit 1" }

含义是：当本次提交同时没有改动docs/目录与packages/core/strapi/（TypeDoc 入口所在包）时，直接跳过部署。由于 Exports 板块依赖packages/core/strapi的源码生成，任何 PR 只要不触及这两处，文档站内容就不会变化，从而避免无意义的重复构建。

IDE 与 Babel 配置说明

• tsconfig.json 开头明确注释“此文件不会被docusaurus start/build使用”，它继承@docusaurus/tsconfig并开启strict与verbatimModuleSyntax，纯粹为 IDE 类型检查与自动补全服务，exclude掉.docusaurus与build两个生成目录；
• babel.config.js 仅一行presets: ['@docusaurus/babel/preset']，供 MDX/JSX 组件使用 Docusaurus 官方 Babel 预设。

小结与适用前提

回到 README 的最小流程：yarn install→yarn start（热更新开发）→yarn build（产出可静态托管的build/）。在此基础上，本仓库文档站的关键工程事实是：

1. 站点基于 Docusaurus 3.10.1 经典预设，五个板块侧边栏全部由目录结构自动生成；
2. “Exports”API 参考板块由 TypeDoc 在构建/开发期从 packages/core/strapi/src/admin.ts 实时生成，输出目录docs/exports属 gitignore 的生成物；
3. 自定义 remark 插件保证从 design-system 提取的 JSDoc 中 Storybook 链接在站点内可正常解析；
4. 部署侧用vercel.json的ignoreCommand将重建范围精确收敛到“文档目录 + core 包”两个耦合面。

适用前提：以上均针对当前仓库docs/目录的提交状态；yarn start需要能在本地同时访问packages/core/strapi的源码（TypeDoc 入口位于仓库根相对路径../packages/core/strapi/...），因此应在完整克隆的 monorepo 根下运行，而非单独 checkoutdocs/目录。

【免费下载链接】strapi🚀 Strapi is the leading open-source headless CMS. It’s 100% JavaScript/TypeScript, fully customizable, and developer-first.项目地址: https://gitcode.com/GitHub_Trending/st/strapi