Docusaurus 2 文档站点实战从 CLI 脚手架到 Vercel 零配置部署【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples本文以仓库中 framework-boilerplates/docusaurus-2 示例为蓝本完整讲解如何使用 Docusaurus 官方 CLI 初始化一个经典classic模板站点理解其目录结构与核心配置并借助 Vercel 的零配置能力一键完成构建与部署。读完本文你将掌握从npx create-docusaurus创建项目、npm run start本地调试、npm run build生产构建到推送到 Git 仓库后由 Vercel 自动识别 Next.js 系静态站点框架并完成部署的完整闭环。一、示例概览一个可零配置部署的 Docusaurus 2 站点仓库中的 README.md 明确指出framework-boilerplates/docusaurus-2目录是一个Docusaurus 2 站点的精简示例其核心卖点是可以零配置zero configuration部署到 Vercel。这意味着该示例刻意不携带vercel.json等部署配置文件——与仓库中其他需要显式声明路由重写rewrite规则的示例如 cdn/api-proxy-rewrite、cdn/mintlify-docs-rewrite形成对比。Vercel 平台会自动检测项目中的docusaurus.config.js与package.json依赖识别出这是一个 Docusaurus 静态站点从而自动套用构建命令npm run build 输出目录build的默认部署策略。从源码结构看该示例由以下部分组成docusaurus.config.js站点全局配置标题、导航栏、预设、主题等package.json依赖与 npm 脚本清单sidebars.js文档侧边栏生成策略docs/Markdown/MDX 文档内容也是教程模块的数据源blog/博客文章含作者配置authors.ymlsrc/pages/独立页面React 组件或 Markdownsrc/components/可复用组件如首页特性卡片HomepageFeaturessrc/css/custom.css自定义样式static/静态资源logo、favicon、SVG 插图babel.config.jsBabel 预设。二、初始化项目使用 Docusaurus CLI 脚手架2.1 脚手架命令原文档给出的一行命令即可创建一个全新的 Docusaurus 2 站点npx create-docusauruslatest my-website classicmy-website目标目录名可替换为你自己的项目名classic模板名即官方经典模板内置了文档、博客、首页三个模块的组合也是 docs/intro.md 中npm init docusauruslatest my-website classic所对应的等价写法npm init与npx两种入口最终都调用同一个脚手架包。命令执行后会自动安装全部依赖无需再手动npm install。经典模板的依赖与版本约束可参考本示例的 package.json依赖版本示例作用docusaurus/core2.0.1Docusaurus 核心框架docusaurus/preset-classic2.0.1经典预设集成 docs / blog / pages / thememdx-js/react^1.6.22MDX 渲染支持clsx^1.2.1条件拼接 className 的工具库prism-react-renderer^1.3.5代码块语法高亮react/react-dom^17.0.2前端运行时同时package.json 中声明了engines: { node: 22.x }因此建议在 Node.js 22 环境下运行确保构建行为与示例一致。2.2 启动本地开发服务器cd my-website npm run startnpm run start内部调用的是 package.json 中定义的脚本start: docusaurus start。它会在本地构建站点启动开发服务器并监听 http://localhost:3000/开启热更新——修改docs/intro.md等内容后页面自动刷新无需手动重启。此外package.json 还提供了一批官方脚本构成完整的站点生命周期管理脚本命令用途startdocusaurus start本地开发服务器热更新builddocusaurus build生产构建输出到build/目录servedocusaurus serve本地预览生产构建产物deploydocusaurus deploy部署到 GitHub Pagesswizzledocusaurus swizzle弹出eject主题组件进行定制cleardocusaurus clear清理构建缓存write-translationsdocusaurus write-translations生成翻译资源文件write-heading-idsdocusaurus write-heading-ids为文档标题补充锚点 id三、核心配置解析docusaurus.config.jsdocusaurus.config.js 是站点的总开关。文件开头使用了// ts-check与type {import(docusaurus/types).Config}类型注解使配置获得 IDE 自动补全与类型检查能力。以下逐段拆解其关键配置项。3.1 站点元信息title: My Site, tagline: Dinosaurs are cool, url: https://your-docusaurus-test-site.com, baseUrl: /, onBrokenLinks: throw, onBrokenMarkdownLinks: warn, favicon: img/favicon.ico,title/tagline站点标题与副标题会显示在浏览器标签页与首页 Hero 区域src/pages/index.js 通过useDocusaurusContext()读取siteConfig渲染url部署后的站点根地址部署到 Vercel 后应替换为你的实际域名如https://xxx.vercel.appbaseUrl站点根路径单站点部署保持/即可onBrokenLinks: throw构建时若发现失效链接直接抛出错误从源头杜绝死链适合文档站点这种对完整性要求高的场景onBrokenMarkdownLinks: warnMarkdown 内部链接失效时仅告警不中断构建。3.2 i18n 国际化字段i18n: { defaultLocale: en, locales: [en], },即使用户当前不做多语言官方也建议保留该字段以设置html lang元信息。若站点为中文可将defaultLocale与locales改为zh-Hans。3.3 classic 预设presets: [ [ classic, { docs: { sidebarPath: require.resolve(./sidebars.js), editUrl: https://github.com/facebook/docusaurus/tree/main/..., }, blog: { showReadingTime: true, editUrl: https://github.com/facebook/docusaurus/tree/main/..., }, theme: { customCss: require.resolve(./src/css/custom.css), }, }, ], ],docs.sidebarPath指向 sidebars.js用于生成文档侧边栏docs.editUrl/blog.editUrl为每个文档页生成编辑此页链接实际项目中应改为你自己的仓库地址不需要时可直接删除blog.showReadingTime: true在博客文章头部展示预计阅读时长theme.customCss注入 src/css/custom.css 自定义全局样式。3.4 主题配置导航栏、页脚与代码高亮themeConfig中定义了三块navbar导航栏titlelogo指向static/img/logo.svg组合品牌区items依次放置Tutorialtype: doc指向docs/intro、Blogto: /blog、GitHub右侧外链footer页脚style: dark按 Docs / Community / More 三组组织链接copyright使用new Date().getFullYear()动态生成年份prism代码高亮通过prism-react-renderer的 GitHub 主题作为亮色主题、Dracula 主题作为暗色主题docusaurus.config.js 顶部即引入了这两个主题包。3.5 侧边栏sidebars.jssidebars.js 默认采用自动生成策略tutorialSidebar: [{type: autogenerated, dirName: .}],即根据docs/目录的文件结构与 front matter 中的sidebar_position自动生成有序侧边栏并提供上一篇/下一篇导航。注释中还给出了手写侧边栏的示例type: categoryitems适用于需要精确控制文档分组顺序的场景。四、内容体系docs、blog 与 pages 三驾马车4.1 文档模块docs/文档是一组通过侧边栏、上一篇/下一篇导航与版本管理串联起来的页面。新建文档只需在 docs/ 下添加 Markdown 文件# Hello This is my **first Docusaurus document**!访问地址即 http://localhost:3000/docs/hello。若要自定义侧边栏标签与排序在文件头部加入 front matter--- sidebar_label: Hi! sidebar_position: 3 --- # Hello本示例的 docs/tutorial-basics/ 还演示了_category_.json分类配置、MDX 功能页markdown-features.mdx以及恭喜完成教程的收尾页congratulations.mddocs/tutorial-extras/ 则展示了多版本管理manage-docs-versions.md与站点翻译translate-your-site.md两个进阶主题。4.2 博客模块blog/blog/ 下的 Markdown/MDX 文件会自动生成为博客文章支持 front matter 指定authors、tags、date等元信息authors.yml集中维护作者资料示例中既有普通 Markdown 文章2019-05-28-first-blog-post.md、2019-05-29-long-blog-post.md也有带图片横幅的 MDX 文章2021-08-01-mdx-blog-post.mdx与2021-08-26-welcome/。4.3 独立页面src/pages/向 src/pages/ 添加Markdown 或 React 文件即可生成独立路由规则如下src/pages/index.js→/src/pages/foo.md→/foosrc/pages/foo/bar.js→/foo/barReact 页面写法示例来自 docs/tutorial-basics/create-a-page.mdimport React from react; import Layout from theme/Layout; export default function MyReactPage() { return ( Layout h1My React page/h1 pThis is a React page/p /Layout ); }Markdown 页面则只需一个# 标题即可。本示例的首页 src/pages/index.js 是一个更复杂的 React 页面它组合了 Hero 横幅读取siteConfig.title/tagline、引导按钮跳转/docs/intro与 HomepageFeatures 三张特性卡片Easy to Use、Focus on What Matters、Powered by React对应static/img/下的三张 SVG 插图。五、构建与本地预览Docusaurus 本质是一个静态站点生成器SSG / Jamstack它把 Markdown、MDX 与 React 编译为一组纯静态的 HTML、JavaScript 和 CSS 文件因此可以部署到几乎任何托管平台。5.1 生产构建npm run buildbuild命令执行后产物输出到build/目录。构建阶段会执行链接完整性检查对应onBrokenLinks: throw策略保证产出站点无死链。5.2 本地预览构建产物npm run serveserve会在本地把build/目录作为一个静态站点伺服起来默认 http://localhost:3000/用于在推送到线上前验证生产构建效果与npm run start的开发模式相互独立。六、部署到 Vercel零配置一键发布回到本示例的主题——零配置部署。整个过程可以归纳为三步初始化npx create-docusauruslatest my-website classic生成站点开发npm run start本地编写文档/博客/页面npm run build验证生产构建部署把项目推送到 Git 仓库后在 Vercel 导入该仓库。Vercel 会自动完成框架检测读取 package.json 中的docusaurus/core依赖套用 Docusaurus 预设的构建命令npm run build与输出目录build无需编写任何vercel.json。该示例目录中刻意没有vercel.json这正是零配置的直观体现而仓库中其他需要自定义路由行为的示例如 cdn/api-proxy-rewrite 的vercel.ts、cdn/cms-bulk-redirects 的vercel.ts则通过配置文件显式声明构建与路由规则可作对照学习。6.1 部署前自查清单url与baseUrl是否已改为实际域名docusaurus.config.jsdocs.editUrl/blog.editUrl是否已指向自己的仓库或删除本地npm run build是否零报错通过npm run serve预览的静态站点是否与预期一致。6.2 后续维护每推送到默认分支Vercel 会自动触发一次新的构建与部署若需要多版本文档参考 docs/tutorial-extras/manage-docs-versions.md若需要国际化参考 docs/tutorial-extras/translate-your-site.md 并配置i18n.locales。七、小结本示例用最小化的工程结构证明了 Docusaurus 2 与 Vercel 的组合效率CLI 一条命令完成脚手架本地三条命令start/build/serve覆盖开发与验证推送后由 Vercel 自动识别框架完成零配置部署。对于以文档为核心、追求低维护成本的站点场景这套classic 模板 自动侧边栏 静态产物 平台默认构建的链路是最直接的落地路径相关配置与目录组织方式均可直接参照 framework-boilerplates/docusaurus-2 目录下的完整示例进行改造复用。【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考