使用 RockyDocs 脚本运行 docs.rockylinux.org 网站的本地副本¶

本文档将引导您使用自动化的 rockydocs.sh 脚本，在您的本地计算机上重新创建并运行 docs.rockylinux.org 网站的完整、与生产环境完全一致的副本。

RockyDocs 脚本提供了一种现代化的、自动化的方法，消除了其他方法中手动设置的复杂性，同时提供与生产环境完全相同的行为。

在以下场景下运行文档网站的本地副本可能很有用

您是一名文档作者，希望精确预览您的内容在实时网站上的显示效果
您想在本地跨多个 Rocky Linux 版本（8、9 和 10）测试您的贡献
您对了解或贡献文档基础设施感兴趣
您需要验证您的内容是否能与版本选择器和导航正确渲染

先决条件¶

RockyDocs 脚本会自动处理大多数依赖项，但您需要

Linux 或 macOS 系统（Windows 配合 WSL2 应该也可以）
您的系统上安装了 git
Python 3.8+ 配合 pip，或者 Docker（脚本支持这两种环境）
大约 2GB 的可用磁盘空间用于完整环境

脚本将自动检查并安装其他必需的工具，如 mkdocs、mike 和各种插件。

设置内容环境¶

切换到您要处理 Rocky Linux 文档的目录。我们将此目录称为您的工作区目录。
```
mkdir -p ~/rocky-projects
cd ~/rocky-projects
```
克隆官方 Rocky Linux 文档存储库
```
git clone https://github.com/rocky-linux/documentation.git
cd documentation
```
现在您拥有了包含自动化 rockydocs.sh 脚本的内容存储库。

使用 RockyDocs 脚本的快速入门选项¶

RockyDocs 脚本提供了多种工作流程选项，以适应不同的贡献者需求。请选择最适合您的编写和审阅流程的选项。

理解三步流程

设置（一次性）：创建一个包含 Python 虚拟环境的构建环境，并安装 MkDocs 工具。还会设置将用于所有后续部署的语言配置（精简版或完整版）。这会创建一个单独的构建文件工作区目录，同时保持内容存储库的整洁。

部署：使用 Mike 和设置期间设置的语言配置，将所有 Rocky Linux 版本（8、9、10）构建成一个完整的、版本化的网站。这会创建您在 docs.rockylinux.org 上看到的 Mmulti-version 结构。

提供服务：启动本地 Web 服务器以预览您的更改。静态模式提供预构建的文件（与生产环境完全一致），而实时模式则在您编辑内容时启用自动重新加载。

自定义工作区位置¶

默认情况下，脚本会在您的内容存储库的相对路径 ../rockydocs-workspaces/ 中创建一个工作区。您可以使用 --workspace 选项来自定义此位置。

# Use a custom workspace location
./rockydocs.sh --setup --venv --workspace ~/my-docs-workspace

# The script remembers your choice for future commands
./rockydocs.sh --deploy
./rockydocs.sh --serve --static

工作区的好处

保持您的内容存储库干净，没有构建文件
允许多个文档项目共享相同的构建环境
自动保存您的工作区偏好设置，以便将来使用
智能重用现有存储库，节省磁盘空间和克隆时间

脚本会自动保存您的工作区偏好设置，并在后续命令中重用它。

选项 1：与生产环境完全一致的预览（推荐用于最终审核）¶

此选项提供与实时 docs.rockylinux.org 网站完全相同的体验，非常适合最终内容审核和测试。

设置环境（一次性设置）

# Basic setup (creates workspace in ../rockydocs-workspaces/)
./rockydocs.sh --setup --venv

# Alternative: Custom workspace location
./rockydocs.sh --setup --venv --workspace ~/my-docs-workspace

构建所有文档版本:
```
./rockydocs.sh --deploy
```
启动与生产环境完全一致的网站:
```
./rockydocs.sh --serve --static
```
静态服务模式

这会像生产环境一样提供预先构建的静态文件，没有重定向。非常适合验证您的内容在实时网站上的外观。根 URL (https://:8000/) 直接提供最新内容，就像 docs.rockylinux.org 一样。

注意：您必须再次运行 --deploy 才能看到内容更改，因为这会提供预先构建的文件。
语言支持

默认情况下，脚本会构建英语和乌克兰语版本，以加快设置和构建速度。要使用所有可用语言进行完整测试，请使用 --full 标志。
```
# Full language support setup (config set once)
./rockydocs.sh --setup --venv --full
# Deploy uses setup's language configuration automatically
./rockydocs.sh --deploy
```

选项 2：实时开发模式（最适合主动编写）¶

此选项在您编辑内容文件时自动刷新您的浏览器，非常适合主动编写会话。

设置环境（一次性设置）

# Basic setup
./rockydocs.sh --setup --venv

# Alternative: Custom workspace location
./rockydocs.sh --setup --venv --workspace ~/my-docs-workspace

构建所有文档版本:
```
./rockydocs.sh --deploy
```
启动实时开发服务器:
```
./rockydocs.sh --serve
```
实时开发模式

这提供了实时重新加载 - 编辑 docs/ 目录中的任何 markdown 文件，并在浏览器中即时看到更改。非常适合主动编写和编辑内容。更改会自动显示，无需再次运行 --deploy。

注意：可能包含重定向和与生产环境略有不同的行为。请使用静态模式进行最终验证。

选项 3：双服务器模式（两全其美）¶

此选项同时运行两个服务器，为您提供完整的站点导航和实时内容编辑功能。

设置环境（一次性设置）

# Basic setup
./rockydocs.sh --setup --venv

# Alternative: Custom workspace location
./rockydocs.sh --setup --venv --workspace ~/my-docs-workspace

构建所有文档版本:
```
./rockydocs.sh --deploy
```
启动双服务器:
```
./rockydocs.sh --serve-dual
```
双服务器模式

这同时运行两个服务器，提供两全其美
- 端口 8000：Mike 提供完整的版本选择器和站点导航
- 端口 8001：MkDocs 实时重新加载，实现即时内容更新
根据您需要实时编辑（8001）还是完整的站点测试（8000），在端口之间切换。此模式非常适合希望获得即时内容反馈和完整站点导航测试的贡献者。

选项 4：Docker 环境¶

如果您更喜欢容器化环境，或者不想在本地安装 Python 依赖项，可以使用任何服务模式的 Docker 版本。

Docker 环境的好处

隔离环境：不影响您的本地 Python 安装或系统依赖项
一致的构建：跨不同机器的相同容器环境
易于清理：完成后只需删除容器和镜像
所有服务模式：支持容器中的静态、实时和双服务器模式

设置 Docker 环境:

# Basic Docker setup
./rockydocs.sh --setup --docker

# Alternative: Custom workspace location
./rockydocs.sh --setup --docker --workspace ~/my-docs-workspace

在容器中构建所有版本:
```
./rockydocs.sh --deploy --docker
```

选择您的 Docker 服务模式:

# Production-identical (static)
./rockydocs.sh --serve --docker --static

# Live development with auto-reload
./rockydocs.sh --serve --docker

# Dual servers (containerized)
./rockydocs.sh --serve-dual --docker

查看您的本地文档网站¶

无论使用哪种方法，您现在都可以通过在 Web 浏览器中打开以下地址来查看网站的本地副本：

https://:8000

您应该会看到： - 完整的 Rocky Linux 文档网站 - 完整的导航和搜索功能 - 顶部导航中的版本选择器 - 所有内容与生产站点完全一致 - 没有重定向行为 - 页面直接加载

可用的脚本命令¶

rockydocs.sh 脚本提供了几个有用的命令

主要工作流程命令¶

# Setup commands (run once)
./rockydocs.sh --setup --venv --minimal     # Python virtual environment setup
./rockydocs.sh --setup --docker --minimal   # Docker containerized setup

# Deployment commands (build the site)
./rockydocs.sh --deploy --minimal           # Build all versions (venv)
./rockydocs.sh --deploy --docker --minimal  # Build all versions (Docker)

# Serving commands (start the local website)
./rockydocs.sh --serve --static             # Production-identical static server (venv)
./rockydocs.sh --serve --docker --static    # Production-identical static server (Docker)
./rockydocs.sh --serve                      # Live development server with auto-reload (venv)
./rockydocs.sh --serve --docker             # Live development server with auto-reload (Docker)
./rockydocs.sh --serve-dual                 # Dual servers: mike serve + mkdocs live reload (venv)
./rockydocs.sh --serve-dual --docker        # Dual servers: containerized version (Docker)

维护和信息命令¶

./rockydocs.sh --status                     # Show environment status and information
./rockydocs.sh --clean                      # Clean workspace and build artifacts
./rockydocs.sh --reset                      # Reset saved configuration
./rockydocs.sh --help                       # Show detailed help information

处理不同的 Rocky Linux 版本¶

脚本会根据您的 git 分支自动检测您正在处理哪个版本

# Switch to different versions in your content repository
git checkout rocky-8    # Work on Rocky Linux 8 documentation
git checkout rocky-9    # Work on Rocky Linux 9 documentation
git checkout main       # Work on Rocky Linux 10 documentation

# Rebuild with your changes
./rockydocs.sh --deploy --minimal

当您查看本地网站时，您的更改将显示在相应的版本中。

理解文件夹结构¶

RockyDocs 脚本在内容和构建环境之间实现了清晰的分离

~/rocky-projects/documentation/          # Your content repository (where you edit)
├── docs/                                # Your content files (guides, books, etc.)
├── rockydocs.sh                         # The script
└── .git/                               # Your content git repository

~/rockydocs-workspaces/                  # Build workspace (created by script)
├── docs.rockylinux.org/                # Main build environment
│   ├── venv/                           # Python virtual environment
│   ├── worktrees/                      # Cached copies of doc versions
│   │   ├── main/                       # Rocky Linux 10 content cache
│   │   ├── rocky-8/                    # Rocky Linux 8 content cache  
│   │   └── rocky-9/                    # Rocky Linux 9 content cache
│   ├── site-static/                    # Static site files (for --static mode)
│   ├── content -> worktrees/main/docs  # Symlink to your current version
│   ├── mkdocs.yml                      # Build configuration
│   └── .git/                          # Local build repository
└── app -> docs.rockylinux.org          # Compatibility symlink

要点： - 您的内容存储库保持整洁 - 没有构建文件或依赖项 - 构建工作区完全独立，可以安全删除 - 脚本根据您当前的分支自动管理 content 符号链接 - 缓存的工作树避免了为不同 Rocky 版本重复下载内容 - --clean 命令可以在需要时移除整个构建工作区

更新您的环境¶

以获取官方存储库的最新更改

# This updates both the build environment and content
./rockydocs.sh --deploy --minimal

脚本会自动从所有 Rocky Linux 文档分支获取更新。

故障排除¶

如果您遇到问题

检查系统状态:
```
./rockydocs.sh --status
```

清理并重建:

./rockydocs.sh --clean
./rockydocs.sh --setup --venv --minimal
./rockydocs.sh --deploy --minimal

获取详细帮助:

./rockydocs.sh --help
./rockydocs.sh --setup --help
./rockydocs.sh --serve --help

您的编辑如何流向已构建的站点¶

了解 RockyDocs 脚本如何将您的本地编辑与已部署的网站连接起来，有助于解释为什么会做出某些设计决策以及您的更改如何在已构建的文档中显示。

核心挑战¶

脚本需要同时完成三件事：1. 让您在熟悉的本地存储库中进行编辑 2. 构建多个 Rocky Linux 版本（8、9、10），并具有正确的 git 上下文
3. 立即在构建中反映您的实时编辑

目录结构概述¶

Your editing environment:
~/rocky-projects/documentation/          ← You edit here
├── docs/                               ← Your live content
├── .git/                              ← Your git repository  
└── rockydocs.sh

Build environment (separate):
../rockydocs-workspaces/docs.rockylinux.org/
├── content → (symlink target varies)   ← MkDocs reads from here
├── mkdocs.yml (docs_dir: "content")    ← Always points to symlink
├── worktrees/                          ← Cached content for other versions
│   ├── main/docs/      ← Rocky 10 cached content
│   ├── rocky-8/docs/   ← Rocky 8 cached content  
│   └── rocky-9/docs/   ← Rocky 9 cached content
└── venv/

智能符号链接策略¶

关键创新是构建环境中的一个动态符号链接，称为 content。此符号链接根据您当前正在处理的内容更改其目标。

当您正在编辑 Rocky Linux 10（主分支）时：¶

# Your context:
cd ~/rocky-projects/documentation
git branch  # Shows: * main

# When you run: ./rockydocs.sh --deploy
# Script creates: content → ~/rocky-projects/documentation/docs

# Result: Your live edits appear immediately in builds

构建其他版本时：¶

# Script builds Rocky 8:
# content → ../worktrees/rocky-8/docs (cached Rocky 8 content)

# Script builds Rocky 9:  
# content → ../worktrees/rocky-9/docs (cached Rocky 9 content)

为什么采用这种设计？¶

主分支 → 您的实时文件： - 您正在积极编辑 Rocky Linux 10 的内容 - 实时重新加载：保存文件，在浏览器中即时看到更改 - 使用您存储库的 git 历史记录来获取准确的时间戳

其他分支 → 缓存的工作树
- 您可能没有本地的 rocky-8/rocky-9 分支 - 为每个 Rocky 版本提供完整的 git 上下文 - 允许构建所有版本而不影响您的工作流程

完整的构建流程示例¶

# 1. You edit in your repo
cd ~/rocky-projects/documentation
echo "New troubleshooting tip" >> docs/guides/myguide.md

# 2. You deploy and serve
./rockydocs.sh --deploy
./rockydocs.sh --serve

# 3. Script creates symlink in build environment
# content → ~/rocky-projects/documentation/docs

# 4. MkDocs builds from your live files
# Your changes appear immediately in the local website

此架构的好处¶

即时编辑反映：您的更改无需重新构建即可即时显示
多版本支持：可以构建所有 Rocky 版本，并具有正确的 git 上下文
清晰的分离：您的 git 工作流程完全不受影响
保留 Git 历史记录：每个版本都有准确的时间戳和作者信息
灵活开发：切换分支，脚本会自动适应

符号链接充当 MkDocs 查找内容的“智能指针”，而脚本则根据您当前正在处理的内容动态地重新定向它。这解释了为什么脚本需要单独克隆存储库 - 它会创建一个干净的构建环境，同时保持您的编辑环境的整洁。

备注¶

RockyDocs 脚本在您的内容存储库 **外部** 创建一个工作区，以保持您的 git 工作流程的整洁
所有环境都是完全本地的 - 没有任何内容会自动上传或发布
脚本会自动管理依赖项、端口冲突和清理
Python 虚拟环境和 Docker 方法都提供相同的功能
本地网站包含与生产站点完全相同的 theme、导航和功能
您可以安全地尝试内容更改 - 您的本地环境是完全隔离的
脚本会自动保留 git 历史记录，以确保文档时间戳的准确性

作者：Wale Soyinka