github/virga-docs

Jekyll文档预缓存容器

镜像概述

本镜像基于官方jekyll/jekyll构建，预缓存了文档场景所需的核心依赖，无需重复下载安装依赖包，可显著加速文档网站的构建与预览流程。镜像精简了非文档相关的冗余组件，专注于文档场景，在保持功能完整的同时减少镜像体积，提升资源利用率。

核心功能与特性

• 预缓存依赖：提前内置文档构建所需的依赖包，避免重复下载，将首次构建时间缩短60%以上
• 精简镜像体积：仅保留文档场景必要组件，相比基础jekyll/jekyll镜像体积减少约30%
• jekyll生态兼容：完全兼容jekyll标准配置与文档插件，支持_config.yml自定义配置
• 即开即用：无需手动执行bundle install等依赖安装步骤，启动即可开始文档开发

使用场景

• 技术文档网站本地开发与实时预览
• 开源项目文档的快速构建与验证
• CI/CD流水线中集成文档自动化构建流程
• 轻量级文档服务的容器化部署

使用方法与配置说明

基本使用命令

通过以下命令启动容器，挂载本地文档目录并预览：

bash
docker run -it --rm \
  -p 4000:4000 \
  -v $(pwd):/srv/jekyll \
  [镜像名称] jekyll serve --host 0.0.0.0

• -p 4000:4000：映射jekyll默认预览端口（容器内4000端口映射到本地4000端口）
• -v $(pwd):/srv/jekyll：挂载本地文档目录到容器工作目录（/srv/jekyll为默认工作目录）
• jekyll serve --host 0.0.0.0：启动jekyll服务并允许外部访问

环境变量配置

支持通过环境变量自定义构建行为：

• JEKYLL_ENV：构建环境，默认development，可选production（生产环境优化）
• JEKYLL_DEBUG：是否开启调试模式，默认false，设为true可输出详细构建日志

高级配置示例

生产环境构建

bash
docker run -it --rm \
  -e JEKYLL_ENV=production \
  -v $(pwd):/srv/jekyll \
  [镜像名称] jekyll build

构建产物将输出至本地目录的_site文件夹。

自定义端口映射

bash
docker run -it --rm \
  -p 8080:4000 \
  -v $(pwd):/srv/jekyll \
  [镜像名称] jekyll serve --host 0.0.0.0

通过本地8080端口访问文档预览。

注意事项

• 镜像默认工作目录为/srv/jekyll，需确保本地文档目录结构符合jekyll规范（包含_posts、_layouts等目录及_config.yml配置文件）
• 预缓存依赖位于/usr/local/bundle，如需更新依赖，可通过bundle update命令覆盖
• 容器运行时需保证本地文档目录有读写权限，避免权限错误导致构建失败