rancher/rancher.github.io

Rancher文档网站Jekyll构建镜像

概述

本镜像基于Jekyll构建，专为Rancher文档网站的构建流程设计，提供文档内容的静态化生成能力。集成了Rancher文档专用的配置与依赖，支持Markdown格式文档的解析、Liquid模板渲染及静态HTML文件输出，可用于文档开发、预览与生产环境部署。

核心功能与特性

• 静态网站生成：基于Jekyll核心功能，将Markdown格式的文档源码编译为可直接部署的静态HTML文件
• Rancher文档定制：内置针对Rancher文档的专用配置（如导航结构、样式主题、版本控制逻辑）
• 模板与数据支持：集成Liquid模板引擎及_data目录数据管理，实现文档内容的动态组合与复用
• 构建流程优化：包含文档校验、依赖预安装等流程，确保构建效率与输出一致性

使用场景与适用范围

• 本地文档开发：开发人员实时预览文档修改效果，支持热重载
• CI/CD集成：在持续集成流程中自动构建文档，输出静态文件用于后续部署
• 文档版本管理：配合分支策略实现多版本文档的并行构建与发布
• 生产环境部署：生成优化后的静态文件，直接用于文档站点的生产环境托管

使用方法与配置说明

基本使用（本地预览）

通过docker run命令启动开发服务器，实时预览文档：

bash
docker run -it --rm \
  -v /本地文档源码目录:/srv/jekyll \
  -p 4000:4000 \
  rancher-docs-jekyll:latest \
  jekyll serve --host 0.0.0.0

• -v /本地文档源码目录:/srv/jekyll：挂载本地Rancher文档源码目录至容器工作目录
• -p 4000:4000：映射Jekyll默认预览端口（4000）至本地
• jekyll serve --host 0.0.0.0：启动开发服务器，允许外部访问

访问http://localhost:4000即可预览文档站点，修改本地文档后将自动触发重建与页面刷新。

生产环境构建

生成优化后的静态文件至本地输出目录：

bash
docker run -it --rm \
  -v /本地文档源码目录:/srv/jekyll \
  -v /本地输出目录:/srv/jekyll/_site \
  -e JEKYLL_ENV=production \
  rancher-docs-jekyll:latest \
  jekyll build

• -v /本地输出目录:/srv/jekyll/_site：挂载输出目录，接收生成的静态文件
• -e JEKYLL_ENV=production：指定生产环境，启用代码压缩与优化

Docker Compose配置示例

创建docker-compose.yml简化多环境管理：

yaml
version: '3'
services:
  rancher-docs:
    image: rancher-docs-jekyll:latest
    volumes:
      - ./docs-src:/srv/jekyll        # 本地文档源码目录
      - ./docs-output:/srv/jekyll/_site  # 输出目录（生产构建用）
    ports:
      - "4000:4000"                   # 开发预览端口
    environment:
      - JEKYLL_ENV=development        # 环境变量（development/production）
    command: jekyll serve --host 0.0.0.0  # 默认启动开发服务器

启动服务：docker-compose up
切换生产构建：修改command为jekyll build并调整JEKYLL_ENV=production

配置文件说明

镜像默认使用Rancher文档专用配置，核心配置文件包括：

• _config.yml：Jekyll主配置（站点标题、URL、插件列表等）
• _data/navigation.yml：文档导航菜单定义
• _layouts/：页面布局模板（如文档页、首页布局）
• _includes/：可复用组件（如页眉、页脚、版本选择器）

用户可通过挂载本地配置文件覆盖默认设置，例如：

bash
docker run -it --rm \
  -v /本地文档源码目录:/srv/jekyll \
  -v /本地自定义_config.yml:/srv/jekyll/_config.yml \
  rancher-docs-jekyll:latest \
  jekyll serve