YugabyteDB 文档本地构建指南

YugabyteDB 文档本地构建指南

yugabyte-db yugabyte/yugabyte-db: 是 YugaByte DB 的官方仓库，一个高性能、高可扩展、分布式的 SQL 数据库，支持 PostgreSQL 兼容性。适合对分布式数据库、SQL 数据库和云原生应用的开发者。 项目地址: https://gitcode.com/gh_mirrors/yu/yugabyte-db

前言

作为一款分布式SQL数据库，YugabyteDB提供了完善的文档系统来帮助开发者理解和使用该数据库。本文将详细介绍如何在本地环境中构建YugabyteDB文档网站，方便开发者进行文档的查阅、编辑和贡献。

环境准备

在开始构建文档前，需要确保本地开发环境满足以下基本要求：

基础工具

1. 文本编辑器：推荐使用Visual Studio Code等现代代码编辑器
2. Node.js环境：建议通过NVM安装LTS版本(22.x)
3. Git版本控制：用于代码管理和协作

操作系统特定工具

macOS环境

1. 安装Homebrew包管理器
2. 通过brew安装核心依赖：
   • Git
   • Go语言环境
   • Hugo静态网站生成器
3. 确保Xcode命令行工具已安装

Ubuntu环境

1. 更新apt软件源
2. 安装基础构建工具链
3. 通过apt安装：
   • Git
   • Go语言环境
   • Node.js
   • Python3及pip

Hugo配置优化

Hugo默认使用系统临时目录作为模块缓存，这可能导致一些问题。建议进行以下优化配置：

1. 在shell配置文件(~/.bashrc或~/.zshrc)中添加：

   export HUGO_CACHEDIR=~/.hugo-cache
   

2. 创建缓存目录：

   mkdir ~/.hugo-cache
   

3. 重新加载shell配置使更改生效

文档项目初始化

1. 克隆文档仓库到本地：

   git clone https://<your-repo-path>/yugabyte-db.git
   

2. 进入文档目录：

   cd yugabyte-db/docs
   

3. 安装项目依赖：

   npm ci
   

4. 获取Hugo模块：

   hugo mod get -u
   

文档构建与预览

YugabyteDB文档使用Markdown编写，通过Hugo生成静态网站。提供以下构建方式：

实时开发模式

npm start

此命令会：

1. 启动本地开发服务器
2. 默认监听1313端口
3. 支持文件修改后的实时热更新

快速构建模式

npm run fast

此模式仅构建preview和stable目录，不生成语法图，适合快速验证内容修改。

完整生产构建

npm run build

此命令会执行与CI流水线完全一致的构建过程，生成完整的静态网站到public目录。

常见问题排查

1. 命令行工具缺失：确保xcode-select指向正确目录，包含usr/bin子目录

2. Hugo模块错误：尝试运行hugo mod clean后重新启动服务

3. 依赖过时：定期运行brew update和brew upgrade保持工具最新

4. Node模块缺失：重新运行npm install安装依赖

后续步骤

完成本地环境搭建后，您可以：

1. 编辑现有文档页面
2. 添加新的文档内容
3. 参与文档的改进与优化

通过本地构建环境，开发者可以更高效地参与YugabyteDB文档的完善工作，为社区做出贡献。

yugabyte-db yugabyte/yugabyte-db: 是 YugaByte DB 的官方仓库，一个高性能、高可扩展、分布式的 SQL 数据库，支持 PostgreSQL 兼容性。适合对分布式数据库、SQL 数据库和云原生应用的开发者。 项目地址: https://gitcode.com/gh_mirrors/yu/yugabyte-db