cibuilds/hugo Docker镜像文档

1. 镜像概述和主要用途

cibuilds/hugo是一个基于Hugo静态网站生成器的Docker镜像，集成了HTMLProofer工具用于网站测试。该镜像主要设计为CircleCI 2.0的基础镜像，用于Hugo静态网站项目的自动化构建、测试与部署流程。未来计划扩展支持本地开发环境测试及Travis CI等其他CI/CD平台。

2. 核心功能和特性

• 集成Hugo：内置Hugo静态网站生成器，支持快速构建静态HTML网站。
• 集成HTMLProofer：包含HTMLProofer工具，可对生成的静态网站进行链接有效性、HTML语法正确性等测试。
• CI/CD适配：针对CircleCI 2.0环境优化，可直接作为CI流程中的构建环境。
• 轻量灵活：作为基础镜像设计，支持用户自定义构建步骤和参数配置。

3. 使用场景和适用范围

• Hugo项目CI/CD：适用于基于Hugo开发的静态网站，在CircleCI 2.0平台实现自动化构建、测试和部署。
• 静态网站质量保障：通过HTMLProofer自动化检测网站链接、HTML结构等问题，提升发布质量。
• 开发环境一致性：未来计划支持本地开发环境，确保开发与CI环境的构建一致性。

4. 详细使用方法和配置说明

4.1 在CircleCI上使用

在CircleCI 2.0中使用该镜像构建Hugo网站，需在项目根目录的.circleci/config.yml中配置以下内容：

version: 2
jobs:
  build:
    docker:
      - image: felicianotech/docker-hugo:0.50  # 指定镜像版本
    working_directory: ~/project  # 工作目录
    steps:
      - checkout  # 拉取代码仓库
      - run:
          name: "构建网站"  # 运行Hugo生成静态文件
          command: HUGO_ENV=production hugo -v -s src/
      - run:
          name: "测试网站"  # 使用HTMLProofer测试生成的网站
          command: htmlproofer src/public --allow-hash-href --check-html --empty-alt-ignore --disable-external

配置说明：

• 镜像指定：docker字段中指定镜像felicianotech/docker-hugo:0.50（版本号需根据实际需求调整）。
• 工作目录：working_directory: ~/project设置CI环境的工作目录。
• 步骤说明：
  • checkout：拉取当前代码仓库到工作目录。
  • 构建步骤：通过HUGO_ENV=production hugo -v -s src/生成网站，其中：
    • HUGO_ENV=production：设置Hugo环境为生产环境。
    • -v：启用详细输出模式，便于调试。
    • -s src/：指定Hugo源文件目录为src（需根据项目结构调整）。
  • 测试步骤：通过htmlproofer测试生成的静态文件（默认输出到src/public），参数说明：
    • --allow-hash-href：允许#开头的锚点链接。
    • --check-html：检查HTML语法有效性。
    • --empty-alt-ignore：忽略图片空alt属性警告。
    • --disable-external：不检查外部链接（可根据需求移除）。

4.2 本地使用（实验性）

虽然镜像主要面向CI环境，也可通过以下命令在本地构建Hugo网站（需替换版本号为实际镜像标签）：

# 本地构建Hugo网站（假设当前目录为项目根目录，Hugo源文件在src/）
docker run --rm -v $(pwd):/project cibuilds/hugo:版本号 \
  sh -c "cd /project && HUGO_ENV=production hugo -v -s src/"

• --rm：容器退出后自动删除。
• -v $(pwd):/project：将本地当前目录挂载到容器内/project目录。
• 命令中通过sh -c执行多步操作，进入挂载目录并运行Hugo构建命令。

5. 配置参数与环境变量

环境变量

• HUGO_ENV：Hugo运行环境，常用值为production（生产环境）或development（开发环境），影响Hugo的配置加载和优化级别。

Hugo命令参数

• -v/--verbose：启用详细输出，便于调试构建过程。
• -s <目录>/--source <目录>：指定Hugo源文件目录（含config.toml、content/等）。
• -t <主题>/--theme <主题>：指定使用的Hugo主题（需提前安装主题）。
• -d <目录>/--destination <目录>：指定静态文件输出目录（默认public/）。

HTMLProofer参数

• --allow-hash-href：允许页面内锚点链接（如#section）。
• --check-html：通过html5lib检查HTML语法正确性。
• --empty-alt-ignore：忽略<img>标签空alt属性的警告。
• --disable-external：禁用外部链接检查（加速测试，需外部检查时移除）。
• --url-ignore <模式>：忽略符合正则模式的链接（如--url-ignore '/example\.com/'）。

6. 构建镜像（维护者指南）

如需构建自定义版本镜像，可按以下步骤操作：

1. 生成Dockerfile：运行项目中的gen-dockerfiles.sh脚本，传入需支持的Hugo版本号：

   # 示例：生成支持Hugo 0.18.1和0.19版本的Dockerfile
   ./gen-dockerfiles.sh 0.18.1 0.19
   

2. 提交与触发构建：将生成的Dockerfile提交至GitHub仓库，CircleCI会自动构建并推送镜像至Docker Hub。

7. 使用示例网站

以下网站基于Hugo开发并使用本镜像构建（部分项目配置开源）：

• Feliciano.Tech（代码仓库）
• HugoNewsletter.com（代码仓库）
• DiscourseHub.com（代码仓库）

8. 反馈与贡献

• 问题反馈：通过GitHub Issues提交bug报告、功能请求或疑问。
• 社区讨论：在Hugo论坛发布主题并@FelicianoTech。
• 代码贡献：欢迎提交Pull Request改进镜像功能或文档。