Docusaurus快速起步

Docusaurus 文档 是使用最广泛的基于 React 开发的Markdown文档平台。我在 Docs-as-Code 调研不同平台，并且尝试了 Nextra 未果，然后我将目光投向了这个由facebook开源的文档平台。

特点

  • Docusaurus是一个易于使用的 静态站点生成器 (类似于 MkDocs文档 / Jekyll静态网站 / Sphinx文档 )

  • 可以快速搭建具有客户端导航的 单页应用 ，这是因为它基于 React 所以不仅能够开箱即用，还提供了定制以用于构建 各种网站 (个人网站、产品、博客、营销主页等等)

简单来说，Docusaurus就是一个高度定制化的 React 内容平台，如果不介意风格单一，想要快速推出 基于内容 的网站，那么参考 最佳Docusaurus站点 可以构建面向用户的生产网站。

快速起步

  • 在安装了 Linux安装Node.js 之后，就可以快速创建Docusaurus网站，以下是我的案例:

创建Docusaurus网站
# 安装参数 --javascript 也可以替换成 --typescript
npx create-docusaurus@latest docs.cloud-atlas.dev classic --javascript

# 可选的安装命令是采用不同的项目管理器初始化
# npm init docusaurus
# yarn create docusaurus
# pnpm create docusaurus
# bunx create-docusaurus
创建Docusaurus网站
# 这里会提示选择JavaScript或TypeScript作为开发语言
✔ Which language do you want to use? › JavaScript
[INFO] Creating new Docusaurus project...
[INFO] Installing dependencies with npm...
[SUCCESS] Created docs.cloud-atlas.dev.
[INFO] Inside that directory, you can run several commands:

  `npm start`
    Starts the development server.

  `npm run build`
    Bundles your website into static files for production.

  `npm run serve`
    Serves the built website locally.

  `npm run deploy`
    Publishes the website to GitHub pages.

We recommend that you begin by typing:

  `cd docs.cloud-atlas.dev`
  `npm start`

Happy building awesome websites!

  • 启动:

启动Docusaurus
npx docusaurus start

注意默认仅监听 localhost ，所以如果需要在所有接口上提供，则参考 Docusaurus docs: CLI 传递参数 --host 0.0.0.0 :

启动Docusaurus监听所有端口
npm run start -- --host 0.0.0.0

# pnpm run start --host 0.0.0.0

此时访问端口 3000 可以看到 Docusaurus 提供了一个默认网站，展示了一个简单的教程

build

构建输出
npm run build

备注

通过 ngpm run build 可以完整构建整个网站，对于 Docusaurus国际化(i18n) 也可以提供多语言服务和自如切换，是最终的展示结果

我遇到报错:

build报错
...
ERROR] Error: Unable to build website for locale en.
    at tryToBuildLocale (/Users/admin/docs/github/huataihuang/docs.cloud-atlas.dev/node_modules/@docusaurus/core/lib/commands/build/build.js:78:15)
    at async /Users/admin/docs/github/huataihuang/docs.cloud-atlas.dev/node_modules/@docusaurus/core/lib/commands/build/build.js:34:9
    ... 4 lines matching cause stack trace ...
    at async file:///Users/admin/docs/github/huataihuang/docs.cloud-atlas.dev/node_modules/@docusaurus/core/bin/docusaurus.mjs:44:3 {
  [cause]: Error: Docusaurus found broken links!

  Please check the pages of your site in the list below, and make sure you don't reference any path that does not exist.
  Note: it's possible to ignore broken links with the 'onBrokenLinks' Docusaurus configuration, and let the build pass.

  It looks like some of the broken links we found appear in many pages of your site.
  Maybe those broken links appear on all pages through your site layout?
  We recommend that you check your theme configuration for such links (particularly, theme navbar and footer).
  Frequent broken links are linking to:
  - /docs/intro

  Exhaustive list of all broken links found:
  - Broken link on source page path = /404.html:
     -> linking to /docs/intro
  - Broken link on source page path = /blog:
     -> linking to /docs/intro
  - Broken link on source page path = /blog/archive:
     -> linking to /docs/intro
...

我经过对比(grep)发现，原来是 Docusaurus国际化(i18n) 时，采用了 docusaurus write-translations 指令来生成 i18n 目录结构以及对应 .json 文件。这些 .json 文件是包含了一些 footer.json 配置文件，其中定制了一些导航链接指向 docs/intro.md ，我在生成了 i18n 目录之后再修订 docusaurus.config.js 中的 docs 路由 routeBasePath 没有及时更新到 i18n ，这样是导致 build 报错的原因。另外，涉及到 src/pages/index.js 包含了 docs/intro 链接需要修订

如果要忽略错误可以调整 docusaurus.config.js 设置(但不建议):

调整 docusaurus.config.js 设置 onBrokenLinks 参数
//onBrokenLinks: 'throw',
onBrokenLinks: 'log',
onBrokenMarkdownLinks: 'warn',

这样 build 就能够顺利完成，就会在项目目录下构建一个 build 目录包含了最终静态文件

serve

  • 启动服务可以从 build 目录提供网站服务，由于是静态网站，所以性能会比开发模式下实时渲染快很多，并且可以使用普通 Nginx 对外提供服务:

提供服务
npm run serve

参考