如何构建StarRocks官方文档

不知道是网络问题还是官网问题，StarRocks文档经常出现卡顿的情况，曾经构建过Flink文档，所以也想尝试自己构建一个StarRocks的本地官方文档
断断续续折腾了好几天，就不废话了，直接上实际步骤

1. 环境

1.1 Linux环境（虚拟机或者wsl都可以，我用的wsl，不要使用cygwin，路径转换有问题）

1.2 nvm、npm、yarn

nvm安装和管理nodejs

2. 直接开始

2.1 git clone doc-build (构建StarRocks文档官方项目)

git clone https://github.com/StarRocks/doc-build.git

2.2 README.md 中有明确的步骤

yarn install --frozen-lockfile
git clone https://gitcode.com/GitHub_Trending/st/starrocks.git temp # 原地址为github，不推荐，建议替换为gitee官方仓库地址加速下载
npm run copy
export DOCUSAURUS_IGNORE_SSG_WARNINGS=true
export NODE_OPTIONS="--max-old-space-size=12192"
yarn clear && yarn build && yarn serve # build 为实际构建静态文档命令，serve 为开启本地web服务
# 在Linux上构建完后可复制构建好的 build 文件夹到任意位置，并在当前位置使用 python -m http.server [port] 开启本地web服务

可以开启两个窗口同时执行 yarn install 和 git clone

2.3 执行`npm run copy`前的几个文件修改(可忽略)

本博客构建的文档版本 3.5 3.1 2.5 的中文和英文文档

doc-build/versions.json 只保留需要的版本

["3.5","3.1","2.5"
]

doc-build/docusaurus.config.js 中需修改的几个位置

  i18n: {defaultLocale: 'en', # 不建议修改为zh，否则搜索跳转功能页面url可能不对，别问我怎么知道的 。。。locales: ['en', 'zh'], # 只保留中英文localeConfigs: {en: {htmlLang: 'en-US',},zh: {htmlLang: 'zh-CN',},},},onlyIncludeVersions: (() => {if (isVersioningDisabled) {return ['current'];} else if (isBuildFast){return [...versions.slice(0, 1)];} else {return ['3.5', '3.1', '2.5']; # 只保留需要的版本}})(),versions: (() => {if (isVersioningDisabled) {return { current: { label: 'current' } };} else {return { # 只保留需要的版本'3.5': { label: 'Latest-3.5', banner: 'none' },'3.1': { label: '3.1', banner: 'none' },'2.5': { label: '2.5', banner: 'none' },};}})(),},

doc-build/src/versions.json 只保留需要的版本(不要删除 main !!!)

[{"branch": "main"},{"branch": "3.5"},{"branch": "3.1"},{"branch": "2.5"}
]

doc-build/src/locales.json

[{"id": "zh-cn","sourceDir": "docs/zh"},{ # 英文文档还是建议保留的，删除用不上的日文文档"id": "en-us","sourceDir": "docs/en"}
]

doc-build/src/config.js

# 将github仓库地址切换为gitee，注意没有.git后缀，多版本构建文档会checkout对应分支
repoUrl: `https://gitcode.com/GitHub_Trending/st/starrocks`

doc-build_IGNORE\cp_common_docs.sh 删除不需要的分支和语言

# 此处贴出我这次修改后的完整内容
#!/bin/bashrm -rf versioned_docs/version-*/release_notes versioned_docs/version-*/developers
rm -rf i18n/zh/docusaurus-plugin-content-docs/version-*/release_notes i18n/zh/docusaurus-plugin-content-docs/version-*/developersmkdir -p releasenotes
mkdir -p commonmkdir -p versioned_docs/version-3.5/_assets/
mkdir -p versioned_docs/version-3.1/_assets/
mkdir -p versioned_docs/version-2.5/_assets/mkdir -p versioned_docs/version-3.5/developers/
mkdir -p versioned_docs/version-3.1/developers/
mkdir -p versioned_docs/version-2.5/developers/mkdir -p i18n/zh/docusaurus-plugin-content-docs/version-3.5/_assets/
mkdir -p i18n/zh/docusaurus-plugin-content-docs/version-3.1/_assets/
mkdir -p i18n/zh/docusaurus-plugin-content-docs/version-2.5/_assets/mkdir -p i18n/zh/docusaurus-plugin-content-docs/version-3.5/developers/
mkdir -p i18n/zh/docusaurus-plugin-content-docs/version-3.1/developers/
mkdir -p i18n/zh/docusaurus-plugin-content-docs/version-2.5/developers/cp versioned_docs/version-3.5/_assets/visualized_heap_profile.png versioned_docs/version-3.1/_assets/
cp versioned_docs/version-3.5/_assets/visualized_heap_profile.png versioned_docs/version-2.5/_assets/
cp versioned_docs/version-3.5/_assets/visualized_heap_profile.png i18n/zh/docusaurus-plugin-content-docs/version-3.5/_assets/
cp versioned_docs/version-3.5/_assets/visualized_heap_profile.png i18n/zh/docusaurus-plugin-content-docs/version-3.1/_assets/
cp versioned_docs/version-3.5/_assets/visualized_heap_profile.png i18n/zh/docusaurus-plugin-content-docs/version-2.5/_assets/cp versioned_docs/version-3.5/_assets/debug_info.png versioned_docs/version-3.1/_assets/
cp versioned_docs/version-3.5/_assets/debug_info.png versioned_docs/version-2.5/_assets/
cp versioned_docs/version-3.5/_assets/debug_info.png i18n/zh/docusaurus-plugin-content-docs/version-3.5/_assets/
cp versioned_docs/version-3.5/_assets/debug_info.png i18n/zh/docusaurus-plugin-content-docs/version-3.1/_assets/
cp versioned_docs/version-3.5/_assets/debug_info.png i18n/zh/docusaurus-plugin-content-docs/version-2.5/_assets/cp versioned_docs/version-3.5/_assets/*trace*.png versioned_docs/version-3.1/_assets/
cp versioned_docs/version-3.5/_assets/*trace*.png versioned_docs/version-2.5/_assets/cp versioned_docs/version-3.5/_assets/*trace*.png i18n/zh/docusaurus-plugin-content-docs/version-3.5/_assets/
cp versioned_docs/version-3.5/_assets/*trace*.png i18n/zh/docusaurus-plugin-content-docs/version-3.1/_assets/
cp versioned_docs/version-3.5/_assets/*trace*.png i18n/zh/docusaurus-plugin-content-docs/version-2.5/_assets/cp versioned_docs/version-3.5/_assets/IDEA*.png versioned_docs/version-2.5/_assets/
cp versioned_docs/version-3.5/_assets/ide*.png versioned_docs/version-2.5/_assets/cp versioned_docs/version-3.5/_assets/IDEA*.png i18n/zh/docusaurus-plugin-content-docs/version-3.1/_assets/
cp versioned_docs/version-3.5/_assets/ide*.png i18n/zh/docusaurus-plugin-content-docs/version-3.1/_assets/
cp versioned_docs/version-3.5/_assets/IDEA*.png i18n/zh/docusaurus-plugin-content-docs/version-2.5/_assets/
cp versioned_docs/version-3.5/_assets/ide*.png i18n/zh/docusaurus-plugin-content-docs/version-2.5/_assets/mv common/releasenotes/en-us/release*.md releasenotes/
mv common/releasenotes/en-us/*or.md releasenotes/mv common/releasenotes/zh-cn/release*.md i18n/zh/docusaurus-plugin-content-docs-releasenotes/current/
mv common/releasenotes/zh-cn/*or.md i18n/zh/docusaurus-plugin-content-docs-releasenotes/current/cp -r common/releasenotes/en-us/build-starrocks versioned_docs/version-3.5/developers/
cp -r common/releasenotes/en-us/code-style-guides versioned_docs/version-3.5/developers/
cp common/releasenotes/en-us/debuginfo.md versioned_docs/version-3.5/developers/
cp -r common/releasenotes/en-us/development-environment versioned_docs/version-3.5/developers/
cp common/releasenotes/en-us/How_to_Contribute.md versioned_docs/version-3.5/developers/
cp common/releasenotes/en-us/jemalloc_heap_profile.md versioned_docs/version-3.5/developers/
cp -r common/releasenotes/en-us/trace-tools versioned_docs/version-3.5/developers/
cp common/releasenotes/en-us/versions.md versioned_docs/version-3.5/developers/cp -r versioned_docs/version-3.5/developers/* versioned_docs/version-3.1/developers/
cp -r versioned_docs/version-3.5/developers/* versioned_docs/version-2.5/developers/cp -r common/releasenotes/zh-cn/build-starrocks         i18n/zh/docusaurus-plugin-content-docs/version-3.5/developers/
cp -r common/releasenotes/zh-cn/code-style-guides       i18n/zh/docusaurus-plugin-content-docs/version-3.5/developers/
cp common/releasenotes/zh-cn/debuginfo.md               i18n/zh/docusaurus-plugin-content-docs/version-3.5/developers/
cp -r common/releasenotes/zh-cn/development-environment i18n/zh/docusaurus-plugin-content-docs/version-3.5/developers/
cp common/releasenotes/zh-cn/How_to_Contribute.md       i18n/zh/docusaurus-plugin-content-docs/version-3.5/developers/
cp common/releasenotes/zh-cn/jemalloc_heap_profile.md   i18n/zh/docusaurus-plugin-content-docs/version-3.5/developers/
cp -r common/releasenotes/zh-cn/trace-tools             i18n/zh/docusaurus-plugin-content-docs/version-3.5/developers/
cp common/releasenotes/zh-cn/versions.md                i18n/zh/docusaurus-plugin-content-docs/version-3.5/developers/cp -r i18n/zh/docusaurus-plugin-content-docs/version-3.5/developers/* i18n/zh/docusaurus-plugin-content-docs/version-3.1/developers/
cp -r i18n/zh/docusaurus-plugin-content-docs/version-3.5/developers/* i18n/zh/docusaurus-plugin-content-docs/version-2.5/developers/rm versioned_docs/version-3.1/developers/versions.md
rm versioned_docs/version-2.5/developers/versions.md
rm i18n/zh/docusaurus-plugin-content-docs/version-3.1/developers/versions.md
rm i18n/zh/docusaurus-plugin-content-docs/version-2.5/developers/versions.md

3. 构建过程和对应截图

3.1 doc-build clone、yarn install、starrocks clone

仓库克隆和yarn安装组件

3.2 执行 npm run copy、设置参数、yarn clear

从package.json可以看出执行的实际命令是 node cli.js copy，cli.js中定义了根据versions.json和locales.json定义下载指定的分支和语言文档文件的操作，最后会调用doc-build\_IGNORE\cp_common_docs.sh复制上述文档到指定位置用于后续的构建
文档复制