如何创建Docusaurus的文档网站

首先了解下什么是Docusaurus？

Docusaurus是指一个开源的构建文档项目，由Meta公司（旧名Facebook）开源维护。是一个静态网页生成器，类似于jekyll，hugo，Docsify，VitePress等的静态生成器工具。

Docusaurus有哪些特点

由 MDX 驱动

节约时间并专注于文档本身。只需要以 Markdown/MDX 格式撰写文档/博客，Docusaurus 就能自动构建生成静态 HTML 文件。用 JSX 和 React 撰写交互组件，并将其嵌入 Markdown。
使用 React 构建

通过编写 React 组件来扩展和自定义你的网页布局。利用插件架构，你可以在设计自己的网站的同时，复用 Docusaurus 插件所创建的数据。
可翻译

开箱即用的本地化。使用 git、Crowdin 或任何其他翻译管理器来翻译你的文档并单独部署。
文档版本化

为你的用户提供所有版本的项目文档。版本化文档可让你的文档发布与项目发行时间保持一致。
内容搜索

让你的社区在文档中轻松找到他们需要的内容。我们支持 Algolia 文档搜索。

开始上手

安装构建工具

Docusaurus由一组npm包组成，因而需要安装Node.js工具集。安装Node.js推荐使用nvm安装，nvm可以方便选择不同版本的Node.js，但版本要求在18.0 或以上。

创建脚手架项目网站

安装 Docusaurus 最简单的方法是使用create-docusaurus命令行工具，它可以帮助你快速搭建一个 Docusaurus 网站的基础框架。你可以在空仓库或现有仓库的任何地方运行这个命令，它会创建一个包含模板文件的新目录。

npx create-docusaurus@latest my-website classic

也可以增加--typescript参数来支持 TypeScript

npx create-docusaurus@latest my-website classic --typescript

classic参数是表示使用经典脚手架模版，classic template包含了 @docusaurus/preset-classic模块，它具有标准文档，博客，自定义页面，和CSS框架（支持黑夜主题模式）的功能。

除了上述方式创建模版项目外，也可以使用如下命令初始化项目：

npm init docusaurus

yarn

yarn create docusaurus

pnpm

pnpm create docusaurus

bunx

bunx create-docusaurus

项目目录结构

假如使用脚手架工具创建了my-website项目后，会自动生成如下文件和目录结构：

my-website
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

目录结构介绍：

/blog/ : 包括了博客Markdown文件。你可以删除该目录以禁止使用博客插件功能，或者你可以当设置了path选项后，更改其名称，可以在博客指南中发掘更多详情。
/docs/ :包含了Markdown格式的文档文件.可以在sidebars.js自定义修改文档在侧边栏的顺序。你可以删除该目录以禁止使用文档插件功能，或者你可以当设置了path选项后，更改其名称，可以在文档指南中发掘更多详情。
/src/ : 可以放置类似pages或自定义的React components的非文档类文件。严格来说，你不一定要把非文档类文件放在这里。不过把它们放在一个集中的目录，可以让代码检查或者处理更为简便。
/src/pages : 在该目录的任何JSX/TSX/MDX文件都将被转化为网页页面。更多详情查看页面指南
/static/ : 静态目录。在该目录里的任何内容都将会被拷贝到最终构建的根目录里。
/docusaurus.config.js : 一个包含了网站配置的配置文件。这相当于Docusaurus v1的siteConfig.js
/package.json : 一个Docusaurus 站点是一个React app. 你可以安装并使用任何 npm 包。
/sidebars.js : 用于指定文档的在侧边栏的顺序。

在已有项目中创建Docusaurus网站（monorepos）

如果你打算用 Docusaurus 来给一个现有的项目搭建文档，单仓模式可能是一种解决方案。单仓允许你在类似项目间共享依赖项。例如，您的网站可以使用本地软件包来展示最新功能，而不是依赖已发布的版本。然后，您的贡献者可以在实现功能的同时更新文档。下面是单仓模式文件夹结构的一个例子：

my-monorepo
├── package-a # 另一个包，你的项目本身
│   ├── src
│   └── package.json #  package-a 的依赖项
├── website   # Docusaurus 根目录
│   ├── docs
│   ├── src
│   └── package.json # Docusaurus 的依赖项
├── package.json # 单仓的共享依赖项

在此样例中，你应该在./my-monorepo目录下运行npx create-docusaurus

如果使用Netlify或Vercel托管网站的提供商时，需要修改指定网站的基础根目录，在该样例中根目录是./。请在部署文档里查询更多配置。

更多真实样例：Docusaurus 和 Jest

更多关于monorepos：Yarn documentation (Yarn不是唯一的设置一个monorepo方式, 但却是一个常见的解决方案)。

运行开发调试服务

要实时预览你的编辑，你可以运行本地开发服务器。它会部署你的网站，并反映最新更改。

cd my-website
npm run start

默认会在浏览器中打开地址 http://localhost:3000.

恭喜！你刚刚成功创建了你的首个 Docusaurus 网站！四处逛逛，看看有什么功能吧。

build构建

Docusaurus 是一款现代化的静态网页生成器。因此，我们需要将网站生成为静态内容，并上传到网络服务器，才能被其他人访问。要构建站点，请使用以下命令：

npm:

npm run build

yarm

yarn build

pnpm

pnpm run build

bun run build

内容将被构建生成在/build目录，该目录下的文件就可以托管到静态文件托管服务的提供上网站上了，如：GitHub pages, Vercel 或 Netlify，详情看deployment

配置搜索

Docusaurus 已官方支持Algolia DocSearch。该服务是免费的，是针对于任何开发者文档和技术博客的，请确保符合Algolia DocSearch的要求：checklist，然后申请应用 apply to the DocSearch program

Docsearch 每周一次爬取你的网站（可以在网页界面上配置具体时间），并将所有内容汇总到一个 Algolia 索引中。随后，你的前端会调用 Algolia API 来直接查询这些内容。如果你的网站不符合免费版托管DocSearch资质，或者你的网站是有防火墙且不是公开的，那么你可以运行你自己的爬虫程序 run your own DocSearch crawler。

如果是应用了预设的经典主题classic就会包含@docusaurus/preset-classic插件，会默认集成了Algolia DocSearch，就不需要额外安装任何东西。

npm install --save @docusaurus/theme-search-algolia

yarn, pnmp, bun

yarn add @docusaurus/theme-search-algolia

pnpm add @docusaurus/theme-search-algolia

bun add @docusaurus/theme-search-algolia

2、docusaurus.config.js配置文件里注册主题

export default {
  title: 'My site',
  // ...
  themes: ['@docusaurus/theme-search-algolia'],
  themeConfig: {
    // ...
  },
};

首先你得在Apply for DocSearch 获取你的配置Algolia index and API key，之后会收到邮件告诉你如何将 DocSearch 添加到你的项目，可以编辑和管理你自己的爬虫配置：the web interface。部署完毕后，索引就立即可用了，所以一般不需要手动配置。

然后在项目配置里algolia字段增加搜索配置连接到Algolia：

export default {
  // ...
  themeConfig: {
    // ...
    algolia: {
      // The application ID provided by Algolia
      appId: 'YOUR_APP_ID',

      // Public API key: it is safe to commit it
      apiKey: 'YOUR_SEARCH_API_KEY',

      indexName: 'YOUR_INDEX_NAME',

      // Optional: see doc section below
      contextualSearch: true,

      // Optional: Specify domains where the navigation should occur through window.location instead on history.push. Useful when our Algolia config crawls multiple documentation sites and we want to navigate with window.location.href to them.
      externalUrlRegex: 'external\\.com|domain\\.com',

      // Optional: Replace parts of the item URLs from Algolia. Useful when using the same search index for multiple deployments using a different baseUrl. You can use regexp or string in the `from` param. For example: localhost:3000 vs myCompany.com/docs
      replaceSearchResultPathname: {
        from: '/docs/', // or as RegExp: /\/docs\//
        to: '/',
      },

      // Optional: Algolia search parameters
      searchParameters: {},

      // Optional: path for search page that enabled by default (`false` to disable it)
      searchPagePath: 'search',

      // Optional: whether the insights feature is enabled or not on Docsearch (`false` by default)
      insights: false,

      //... other Algolia params
    },
  },
};

更多详细配置可查看搜索配置

ON THIS PAGE

如何创建Docusaurus的文档网站#

首先了解下什么是Docusaurus？#

Docusaurus有哪些特点#

开始上手#

安装构建工具#

创建脚手架项目网站#

项目目录结构#

目录结构介绍：#

在已有项目中创建Docusaurus网站（monorepos）#

运行开发调试服务#

build构建#

配置搜索#