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 定义了与这五大板块一一呼应的侧边栏全部由文件系统自动推导autogeneratedconst 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核心为依赖版本作用docusaurus/core3.10.1站点框架核心docusaurus/preset-classic3.10.1经典预设导航、侧边栏、搜索骨架docusaurus/theme-mermaid3.10.1在 Markdown 中渲染 Mermaid 流程图cmfcmf/docusaurus-search-local2.0.1本地全文搜索离线无需外部索引服务docusaurus-plugin-typedoc1.4.2从 TypeScript 源码生成 API 文档typedoc/typedoc-plugin-markdown0.28.19 / 4.11.0TypeDoc 文档生成器及其 Markdown 输出插件react/react-dom18.3.1站点渲染运行时resolutions字段额外锁定了babel/*7.29.7等传递依赖版本避免 Docusaurus 与 monorepo 根工作区之间的依赖冲突。本地开发yarn start$ yarn start启动本地开发服务器并自动打开浏览器窗口文档修改大多可热更新、无需重启。对照 package.json 的 scripts 可以看到start实际是start: TYPEDOC_WATCHtrue docusaurus startTYPEDOC_WATCHtrue这一环境变量并非装饰——docusaurus.config.ts 中 TypeDoc 插件的watch选项正是读取它const pluginTypedocOptions: Parameterstypeof 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/目录之后可托管在任意静态内容服务上。构建期的完整管线包括解析docs/docs/下的guides、docs、api、rfcs四个内容目录及index.md首页运行 TypeDoc 插件把admin.ts入口的导出渲染为docs/exports被.gitignore明确列为生成物/build、.docusaurus、/docs/exports均不入库本地搜索插件建立索引indexBlog: false且博客整体关闭blog: false经自定义 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: falseURL 统一不带尾斜杠onBrokenLinks: warn与markdown.hooks.onBrokenMarkdownLinks: warn坏链只告警不中断构建配合markdown.mermaid: true允许在 MDX 中嵌入流程图。React 解析别名插件配置中注册了一个内联插件resolve-reactplugins通过 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/。在此基础上本仓库文档站的关键工程事实是站点基于 Docusaurus 3.10.1 经典预设五个板块侧边栏全部由目录结构自动生成“Exports”API 参考板块由 TypeDoc 在构建/开发期从 packages/core/strapi/src/admin.ts 实时生成输出目录docs/exports属 gitignore 的生成物自定义 remark 插件保证从 design-system 提取的 JSDoc 中 Storybook 链接在站点内可正常解析部署侧用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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考