工作中的那点事之 Docusaurus

前言

记录一下之前开发的时候的一些关键步骤、代码

版本：3.7.0

国际化

配置文件添加配置：
docusaurus.config.ts

export default {
  i18n: {
    defaultLocale: "zh-CN",
    locales: ["en", "zh-CN"],
    localeConfigs: {
      en: {
        label: "English",
        direction: "ltr",
        path: "en",
      },
      "zh-CN": {
        label: "简体中文",
        direction: "ltr",
      },
    },
  },
  themeConfig: {
    // ...
    navbar: {
      // ...
      items: [
        {
          type: "localeDropdown", //添加选择语言的下拉菜单
          position: "right",
        },
      ],
    },
  },
};

生成其它语言的文件结构

通过下面的命令生成其他语言的文件结构

1	`yarn write-translations --locale en`

i18n 下对应语言的文件夹名称由上面配置的path决定，也就是说en对应的文件夹甚至可以配置成zh。

添加文档的翻译文件

添加文档的翻译文件，则放到docusaurus-plugin-content-docs文件夹下，分别根据生成的 json 文件创建对应版本的翻译文件夹。如果没有分版本的话，那就放到 current 文件夹下。

配置了多语言，但是部分文档没有翻译的话，则会直接使用默认语言。比如上面docs文件夹下还有其他md文件，en下没有，则会直接用docs的内容。

查看效果

本地环境无法直接查看多语言的情况，yarn start查看默认语言，yarn run start --locale en查看其他语言

打包后，查看效果：

资源引入路径添加 cdn 前缀

这部分没有用最新版本的docusaurus测试，版本是2.4.3

编写 webpack 插件

custom-webpack.js

const path = require("path");
const resolve = path.resolve;

module.exports = function (context, options) {
  return {
    name: "custom-webpack",
    configureWebpack(config, isServer, utils) {
      return {
        resolve: {
          alias: {
            "@": resolve("/src"),
          },
        },
        output: {
          publicPath: process.env.PUBLIC_PATH || "/",
        },
      };
    },
  };
};

docusaurus.config.js

const customWebpack = require("../plugins/custom-webpack");
export default {
  plugins: [customWebpack],
};

通过 webpack 插件可以将大部分静态资源的路径添加cdn前缀，但是有几个 css、js 文件不受控制。

添加配置`srrTemplate`

上面提到的“有几个 css、js 文件不受控制”，可以通过srrTemplate配置解决。

搞了好久，还简单看了源码的流程，才发现配置本身就提供ssrTemplate。https://github.com/facebook/docusaurus/discussions/4123。有个discussion讨论了好久，实际上就可以通过这个来实现。

template.js

const publicPath = process.env.PUBLIC_PATH || "/";

module.exports = `
<!DOCTYPE html>
<html <%~ it.htmlAttributes %>>
  <head>
    <meta charset="UTF-8">
    <meta name="generator" content="Docusaurus v<%= it.version %>">
    <% it.metaAttributes.forEach((metaAttribute) => { %>
      <%~ metaAttribute %>
    <% }); %>
    <%~ it.headTags %>
    <% it.stylesheets.forEach((stylesheet) => { %>
      <link rel="stylesheet" href="${publicPath}<%= stylesheet %>" />
    <% }); %>
    <% it.scripts.forEach((script) => { %>
      <script src="${publicPath}<%= script %>" defer></script>
    <% }); %>
  </head>
  <body <%~ it.bodyAttributes %>>
    <%~ it.preBodyTags %>
    <div id="__docusaurus"><%~ it.appHtml %></div>
    <%~ it.postBodyTags %>
  </body>
</html>
`;

docusaurus.config.js

const ssrTemplate = require("./template");

export default {
  ssrTemplate,
};

分版

生成版本相关文件、文件夹

yarn docusaurus docs:version 2.0

会基于当前版本docs生成对应版本，多语言也会生成。不过没有相关的 json 文件，需要重新执行一次yarn write-translations --locale en

添加配置

docusaurus

export default {
  themeConfig: {
    // ...
    navbar: {
      // ...
      items: [
        {
          type: "docsVersionDropdown",
          position: "right",
        },
      ],
    },
  },
  presets: [
    [
      "classic",
      {
        docs: {
          // ...
          lastVersion: "current",
          versions: {
            current: {
              label: "latest",
              path: "",
            },
          },
        },
      },
    ],
  ],
};