Docusaurus文档框架使用

概述

Docusaurus 是专业的文档编写框架，详见官网：https://docusaurus.io/zh-CN/docs

Docusaurus目录结构

1>. 项目整体结构

├─ docusaurus.config.js     # 站点总配置
├─ sidebars.js              # Docs 侧边栏结构
│
├─ docs/                    # 当前版本文档（current）
├─ blog/                    # 博客内容
├─ src/                     # React源码（页面 / 组件）
├─ static/                  # 静态资源文件，如：.css、img、.js等
│
├─ versioned_docs/          # 历史版本文档
├─ versioned_sidebars/      # 历史版本侧边栏
│
├─ i18n/                    # 多语言系统（翻译 + 内容）
│
├─ version-7.3.0/            # 历史版本：文档内容（md）
│  └─ intro.md
│
├─ current.json               # 当前版本 Docs 的 UI / sidebar 文案
├─ version-7.3.0.json         # 7.3.0 版本 Docs 的 UI / sidebar 文案
│
├─ build/                   # 构建产物（部署用）

2>. 多语言目录 i18n 展示如下：

i18n/
├─ zh-CN/   ## 简体中文
│  ├─ docusaurus-plugin-content-docs/  ## 文档内容
│  │  ├─ current/        ## 当前版本内容
│  │  │  ├─ intro.md
│  │  │  └─ api.md
│  │  ├─ version-6.5.0/  ## 6.5.0版本内容
│  │  │  └─ intro.md
│  │  ├─ version-7.0.0/  ## 7.0.0版本内容
│  │  │
│  │  ├─ current.json        ## 当前版本 Docs UI 翻译
│  │  ├─ version-6.5.0.json  ## 6.5.0版本 Docs UI 翻译
│  │  ├─ version-7.0.0.json  ## 7.0.0版本 Docs UI 翻译
│  │
│  ├─ docusaurus-plugin-content-blog/  ## 博客内容
│  │  ├─ 2024-01-01-hello.md
│  │  └─ options.json
│  │
│  ├─ docusaurus-theme-classic/        
│  │  ├─ navbar.json    ## 顶部导航翻译，作用于当前语种的所有版本
│  │  └─ footer.json    ## 底部导航翻译，作用于当前语种的所有版本
│  │
│  └─ code.json  ## 语言文件：定义 React/JS 代码中的可翻译字符串
│
└─ fr/    ## 其它语言
   └─ ...

多语言支持

有些 Docusaurus 文档项目默认仅支持英文，因此初次翻译时，要手动初始化创建其它语言的目录结构

## 初始化各语种文档目录结构
npx docusaurus write-translations --locale zh-CN
npx docusaurus write-translations --locale zh-TW
npx docusaurus write-translations --locale es
npx docusaurus write-translations --locale fr
npx docusaurus write-translations --locale de
npx docusaurus write-translations --locale ja
npx docusaurus write-translations --locale ko
npx docusaurus write-translations --locale pt-BR
npx docusaurus write-translations --locale ru
npx docusaurus write-translations --locale pl
npx docusaurus write-translations --locale tr
npx docusaurus write-translations --locale ar
npx docusaurus write-translations --locale th
npx docusaurus write-translations --locale vi
npx docusaurus write-translations --locale id
npx docusaurus write-translations --locale hi
npx docusaurus write-translations --locale bn-BD
npx docusaurus write-translations --locale ur

页面字符串翻译

将 React/js 页面中的需要翻译的字符串抽取到 i18n/<语言>/code.json 文件中；

1> 抽取JS中需要翻译的字符串：

如下图，项目打包时，translate({ id: 'home.title','Advanced geospatial toolkit for Typescript' }) 会去 i18n/<语言>/code.json 文件中寻找 key 为 home.title 的的字符串，若找到了，则使用 i18n/<语言>/code.json 文件中寻找 key 为 home.title 的字符串；若未找到，则使用默认字符串 'Advanced geospatial toolkit for Typescript'；

2>. 抽取页面中需要翻译的字符串

与“抽取JS中需要翻译的字符串”的原理相同，只是使用的是 Translate 标签，如下：

<Translate id="home.h1">Advanced geospatial toolkit for Typescript</Translate>

添加百度或Google统计

## 安装 Google 统计插件
npm install --save @docusaurus/plugin-google-gtag