Rolldown 文档贡献指南基于 VitePress 的本地开发、构建与部署全流程解析【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldownRolldown 的官方文档站点docs 目录基于 VitePress 展开结合仓库内真实的站点配置、脚本与生成工具源码完整讲解如何为 Rolldown 文档贡献内容。读完本文你将掌握启动文档开发服务器、热更新编辑 Markdown、理解站点结构与侧边栏配置、执行生产构建与本地预览、以及了解 API 参考文档自动生成机制的全套流程。文档的定位docs目录即站点源码Rolldown 的文档站不是一个独立仓库而是直接存放在当前仓库根目录下的 docs 目录中由 VitePress 渲染为静态站点。这意味着贡献文档就是贡献代码你只需要修改docs下的 Markdown 文件并提交站点的导航、搜索、OG 图、甚至 API 参考页都会随之联动更新。关于站点内容的组织方式docs/development-guide/docs.md 给出了最核心的几条结论文档引擎为VitePress站点源码位于docs可通过pnpm run docs在项目根目录启动文档开发服务器站点结构导航、侧边栏等在docs/.vitepress/config.ts中配置构建产物可用pnpm docs:buildpnpm docs:preview本地预览。快速开始在项目根目录启动文档开发服务器在项目根目录执行pnpm run docs该命令会启动 VitePress 开发服务器打开浏览器即可实时预览文档站。此后直接编辑docs下的任意 Markdown 文件页面会立刻热更新无需重启或手动刷新这是 VitePress 内置的开发体验。从仓库根目录的 package.json 可以看到该命令的真实定义docs: pnpm --filter rolldown-docs run dev它通过 pnpm workspace 过滤到rolldown-docs这个子包再执行其dev脚本。而rolldown-docs包即 docs/package.json中的定义是dev: vitepress dev即最终等价于在docs目录下运行vitepress dev。环境前提当前仓库使用 pnpm workspace见根目录 pnpm-workspace.yaml管理依赖docs与packages等子包共享一个锁文件。首次运行前需先执行pnpm install安装依赖且本机需要可用的 Node.js 与 pnpm 环境。为什么文档明确要求用pnpm run docs而非pnpm docs原文档特别提醒由于pnpm docs命令被用于打开npm中的模块说明因此请使用pnpm run docs。这是 npm/pnpm 脚本机制的一个经典陷阱当包内同时存在某个依赖包提供的同名命令时pnpm docs会优先解析到 node_modules 中可执行文件此处为 npm 的docs命令作用是打开某个模块在 npm 官网的说明页而不是仓库package.json中定义的docs脚本。只有显式写出pnpm run docs才能保证执行的是本项目定义的文档开发脚本。文档站点结构一览docs目录采用内容即目录的组织方式主要结构与当前仓库实况对应如下路径用途docs/guide入门指南Introduction、Getting Started、Notable Features、Troubleshootingdocs/in-depth深度专题模块类型、外部模块、代码分割、Tree Shaking、Lazy Barrel 优化等docs/glossary术语表Entry、Entry Chunk、Barrel Module 等docs/apisAPI 文档Bundler API、Plugin API、CLI、Rust Cratesdocs/builtin-plugins内置插件文档bundle-analyzer、replace、esm-external-require 等docs/development-guide开发者指南环境搭建、测试、基准、Profiling 等本文即属此节docs/.vitepressVitePress 站点配置、主题与生成脚本docs/public静态资源Logo、OG 图等页面间的导航关系由 docs/.vitepress/config.ts 中的sidebarForGuide、sidebarForApi、sidebarForPlugins、sidebarForDevGuide、sidebarForResources等数据结构定义。例如本文所在的开发指南节/development-guide/与/contribution-guide/路径共用sidebarForDevGuide其中明确将 Docs 文档 挂在了 Development Guide 分组之下与 Setup the project、Building and running、Testing、Benchmarking、Tracing/Logging、Profiling、Coding Style 并列。站点配置深入docs/.vitepress/config.ts原文档指出站点结构配置位于docs/.vitepress/config.tsSite Config Reference 是 VitePress 官方的完整配置参考。结合仓库源码这份配置远不止侧边栏它还承载了若干与文档贡献直接相关的关键能力搜索配置了 Algolia DocSearchprovider: algoliaindexName 为rolldownApp ID 与 API Key 通过ALGOLIA_APP_ID、ALGOLIA_API_KEY环境变量注入API 参考侧边栏通过getTypedocSidebar()与getOptionsSidebar()读取docs/reference/typedoc-sidebar.json和options-sidebar.json由构建脚本生成并为Function.rolldown、Interface.Plugin等重要 API 打上★标记、置顶排序LLM 友好配置了vitepress-plugin-llmsconfig.ts 中llmstxt插件并明确ignoreFiles: [development-guide/**/*, ...]即开发指南类文档不进入 llms.txt 索引Markdown 增强通过graphvizMarkdownPlugin支持 Graphviz 图hooks 图处理器在 docs/.vitepress/markdown-hooks-graph.ts 中定义通过groupIconMdPlugin支持代码块分组图标OG 图片自动生成transformPageData中为除首页外的每个 Markdown 页面自动调用addOgImage生成 Open Graph 分享图编辑链接配置了editLink.pattern指向仓库的docs/:path因此每个页面右下角都有 Edit this page on GitHub 入口方便贡献者直达源码文件自动生成的reference/参考文档页面除外配置中已显式关闭。主题与组件站点主题继承自voidzero-dev/vitepress-theme见 docs/.vitepress/theme/index.ts并注册了DefinedIn组件与vitepress-plugin-feedback-tracker反馈插件。首页布局由 docs/.vitepress/theme/Home.vue 驱动docs 根目录的 docs/index.md 只是薄薄一层 home layout 壳。API 参考文档的自动生成机制这是 docs/.vitepress/config.ts 之外的另一个文档构建环节值得单独说明。docs包中定义了generate脚本generate: node .vitepress/scripts/generate-reference.ts其实现位于 docs/.vitepress/scripts/generate-reference.ts流程为读取 packages/rolldown/package.json 的exports字段自动发现所有公开 API 入口排除./experimental与./parallelPlugin使用TypeDoc配合typedoc-plugin-markdown、typedoc-vitepress-theme、typedoc-plugin-merge-modules等插件将 TypeScript 源码转换为docs/reference/下的 Markdown 文档借助 docs/.vitepress/scripts/extract-options-plugin.ts 从参考文档中抽取 Options 的属性表如ChecksOptions、TreeshakingOptions等类型的 Properties 段生成options-sidebar.json将文档内https://rolldown.rs/...的绝对链接改写为站内相对路径避免外链新开标签页。对贡献者的意义docs/reference/是构建时自动生成的产物不应手工编辑修改 API 相关文档的正确方式是修改 packages/rolldown 下 TypeScript 源码中的 JSDoc 注释再重新运行generate。构建、预览与部署原文档给出的构建命令为pnpm docs:build pnpm docs:preview从根目录 package.json 可以看到这两个命令的完整定义docs:build: pnpm --filter rolldown-docs run generate pnpm --filter rolldown-docs run build, docs:preview: pnpm --filter rolldown-docs run preview也就是说pnpm docs:build实际执行了两步generate运行 TypeDoc 生成docs/reference/API 参考文档与侧边栏 JSONbuild运行vitepress build产出静态站点到docs/.vitepress/dist。之后pnpm docs:preview即vitepress preview在本地启动一个静态服务器供你验收构建产物。原文档还特别指出如果只是贡献 Markdown 内容、没有改动文档构建相关配置那么贡献时不需要执行这步直接用pnpm run docs开发即可构建验收仅在改动构建配置时有必要。关于部署仓库在 docs/wrangler.jsonc 中配置了 Cloudflare Workers 静态资源部署assets.directory指向./.vitepress/dist404 处理使用404-page根目录还有对应的docs:void脚本先generate再void deploy。日常贡献无需关心部署环节提交到主分支后由维护流程处理。贡献文档的推荐工作流综合原文档与仓库实际配置为 Rolldown 文档做贡献的完整流程如下安装依赖在仓库根目录执行pnpm installworkspace 模式docs与各包共享依赖启动开发服务器在项目根目录执行pnpm run docs注意不要用pnpm docs避免命中 npm 的 docs 命令编辑内容修改docs下对应的 Markdown 文件浏览器即时热更新新增页面时注意在 docs/.vitepress/config.ts 的对应 sidebar 数组中登记链接本地验收可选若改动涉及构建配置执行pnpm docs:build生成参考文档并pnpm docs:preview预览提交经由编辑链接或常规 PR 流程提交变更。通过这套流程Rolldown 的文档站可以像代码一样被版本管理、评审与自动化构建而 docs/development-guide/docs.md 正是这份工作流的起点入口。【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Rolldown 文档贡献指南：基于 VitePress 的本地开发、构建与部署全流程解析
Rolldown 文档贡献指南基于 VitePress 的本地开发、构建与部署全流程解析【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldownRolldown 的官方文档站点docs 目录基于 VitePress 展开结合仓库内真实的站点配置、脚本与生成工具源码完整讲解如何为 Rolldown 文档贡献内容。读完本文你将掌握启动文档开发服务器、热更新编辑 Markdown、理解站点结构与侧边栏配置、执行生产构建与本地预览、以及了解 API 参考文档自动生成机制的全套流程。文档的定位docs目录即站点源码Rolldown 的文档站不是一个独立仓库而是直接存放在当前仓库根目录下的 docs 目录中由 VitePress 渲染为静态站点。这意味着贡献文档就是贡献代码你只需要修改docs下的 Markdown 文件并提交站点的导航、搜索、OG 图、甚至 API 参考页都会随之联动更新。关于站点内容的组织方式docs/development-guide/docs.md 给出了最核心的几条结论文档引擎为VitePress站点源码位于docs可通过pnpm run docs在项目根目录启动文档开发服务器站点结构导航、侧边栏等在docs/.vitepress/config.ts中配置构建产物可用pnpm docs:buildpnpm docs:preview本地预览。快速开始在项目根目录启动文档开发服务器在项目根目录执行pnpm run docs该命令会启动 VitePress 开发服务器打开浏览器即可实时预览文档站。此后直接编辑docs下的任意 Markdown 文件页面会立刻热更新无需重启或手动刷新这是 VitePress 内置的开发体验。从仓库根目录的 package.json 可以看到该命令的真实定义docs: pnpm --filter rolldown-docs run dev它通过 pnpm workspace 过滤到rolldown-docs这个子包再执行其dev脚本。而rolldown-docs包即 docs/package.json中的定义是dev: vitepress dev即最终等价于在docs目录下运行vitepress dev。环境前提当前仓库使用 pnpm workspace见根目录 pnpm-workspace.yaml管理依赖docs与packages等子包共享一个锁文件。首次运行前需先执行pnpm install安装依赖且本机需要可用的 Node.js 与 pnpm 环境。为什么文档明确要求用pnpm run docs而非pnpm docs原文档特别提醒由于pnpm docs命令被用于打开npm中的模块说明因此请使用pnpm run docs。这是 npm/pnpm 脚本机制的一个经典陷阱当包内同时存在某个依赖包提供的同名命令时pnpm docs会优先解析到 node_modules 中可执行文件此处为 npm 的docs命令作用是打开某个模块在 npm 官网的说明页而不是仓库package.json中定义的docs脚本。只有显式写出pnpm run docs才能保证执行的是本项目定义的文档开发脚本。文档站点结构一览docs目录采用内容即目录的组织方式主要结构与当前仓库实况对应如下路径用途docs/guide入门指南Introduction、Getting Started、Notable Features、Troubleshootingdocs/in-depth深度专题模块类型、外部模块、代码分割、Tree Shaking、Lazy Barrel 优化等docs/glossary术语表Entry、Entry Chunk、Barrel Module 等docs/apisAPI 文档Bundler API、Plugin API、CLI、Rust Cratesdocs/builtin-plugins内置插件文档bundle-analyzer、replace、esm-external-require 等docs/development-guide开发者指南环境搭建、测试、基准、Profiling 等本文即属此节docs/.vitepressVitePress 站点配置、主题与生成脚本docs/public静态资源Logo、OG 图等页面间的导航关系由 docs/.vitepress/config.ts 中的sidebarForGuide、sidebarForApi、sidebarForPlugins、sidebarForDevGuide、sidebarForResources等数据结构定义。例如本文所在的开发指南节/development-guide/与/contribution-guide/路径共用sidebarForDevGuide其中明确将 Docs 文档 挂在了 Development Guide 分组之下与 Setup the project、Building and running、Testing、Benchmarking、Tracing/Logging、Profiling、Coding Style 并列。站点配置深入docs/.vitepress/config.ts原文档指出站点结构配置位于docs/.vitepress/config.tsSite Config Reference 是 VitePress 官方的完整配置参考。结合仓库源码这份配置远不止侧边栏它还承载了若干与文档贡献直接相关的关键能力搜索配置了 Algolia DocSearchprovider: algoliaindexName 为rolldownApp ID 与 API Key 通过ALGOLIA_APP_ID、ALGOLIA_API_KEY环境变量注入API 参考侧边栏通过getTypedocSidebar()与getOptionsSidebar()读取docs/reference/typedoc-sidebar.json和options-sidebar.json由构建脚本生成并为Function.rolldown、Interface.Plugin等重要 API 打上★标记、置顶排序LLM 友好配置了vitepress-plugin-llmsconfig.ts 中llmstxt插件并明确ignoreFiles: [development-guide/**/*, ...]即开发指南类文档不进入 llms.txt 索引Markdown 增强通过graphvizMarkdownPlugin支持 Graphviz 图hooks 图处理器在 docs/.vitepress/markdown-hooks-graph.ts 中定义通过groupIconMdPlugin支持代码块分组图标OG 图片自动生成transformPageData中为除首页外的每个 Markdown 页面自动调用addOgImage生成 Open Graph 分享图编辑链接配置了editLink.pattern指向仓库的docs/:path因此每个页面右下角都有 Edit this page on GitHub 入口方便贡献者直达源码文件自动生成的reference/参考文档页面除外配置中已显式关闭。主题与组件站点主题继承自voidzero-dev/vitepress-theme见 docs/.vitepress/theme/index.ts并注册了DefinedIn组件与vitepress-plugin-feedback-tracker反馈插件。首页布局由 docs/.vitepress/theme/Home.vue 驱动docs 根目录的 docs/index.md 只是薄薄一层 home layout 壳。API 参考文档的自动生成机制这是 docs/.vitepress/config.ts 之外的另一个文档构建环节值得单独说明。docs包中定义了generate脚本generate: node .vitepress/scripts/generate-reference.ts其实现位于 docs/.vitepress/scripts/generate-reference.ts流程为读取 packages/rolldown/package.json 的exports字段自动发现所有公开 API 入口排除./experimental与./parallelPlugin使用TypeDoc配合typedoc-plugin-markdown、typedoc-vitepress-theme、typedoc-plugin-merge-modules等插件将 TypeScript 源码转换为docs/reference/下的 Markdown 文档借助 docs/.vitepress/scripts/extract-options-plugin.ts 从参考文档中抽取 Options 的属性表如ChecksOptions、TreeshakingOptions等类型的 Properties 段生成options-sidebar.json将文档内https://rolldown.rs/...的绝对链接改写为站内相对路径避免外链新开标签页。对贡献者的意义docs/reference/是构建时自动生成的产物不应手工编辑修改 API 相关文档的正确方式是修改 packages/rolldown 下 TypeScript 源码中的 JSDoc 注释再重新运行generate。构建、预览与部署原文档给出的构建命令为pnpm docs:build pnpm docs:preview从根目录 package.json 可以看到这两个命令的完整定义docs:build: pnpm --filter rolldown-docs run generate pnpm --filter rolldown-docs run build, docs:preview: pnpm --filter rolldown-docs run preview也就是说pnpm docs:build实际执行了两步generate运行 TypeDoc 生成docs/reference/API 参考文档与侧边栏 JSONbuild运行vitepress build产出静态站点到docs/.vitepress/dist。之后pnpm docs:preview即vitepress preview在本地启动一个静态服务器供你验收构建产物。原文档还特别指出如果只是贡献 Markdown 内容、没有改动文档构建相关配置那么贡献时不需要执行这步直接用pnpm run docs开发即可构建验收仅在改动构建配置时有必要。关于部署仓库在 docs/wrangler.jsonc 中配置了 Cloudflare Workers 静态资源部署assets.directory指向./.vitepress/dist404 处理使用404-page根目录还有对应的docs:void脚本先generate再void deploy。日常贡献无需关心部署环节提交到主分支后由维护流程处理。贡献文档的推荐工作流综合原文档与仓库实际配置为 Rolldown 文档做贡献的完整流程如下安装依赖在仓库根目录执行pnpm installworkspace 模式docs与各包共享依赖启动开发服务器在项目根目录执行pnpm run docs注意不要用pnpm docs避免命中 npm 的 docs 命令编辑内容修改docs下对应的 Markdown 文件浏览器即时热更新新增页面时注意在 docs/.vitepress/config.ts 的对应 sidebar 数组中登记链接本地验收可选若改动涉及构建配置执行pnpm docs:build生成参考文档并pnpm docs:preview预览提交经由编辑链接或常规 PR 流程提交变更。通过这套流程Rolldown 的文档站可以像代码一样被版本管理、评审与自动化构建而 docs/development-guide/docs.md 正是这份工作流的起点入口。【免费下载链接】rolldownFast Rust bundler for JavaScript/TypeScript with Rollup-compatible API.项目地址: https://gitcode.com/GitHub_Trending/ro/rolldown创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
