ajhalili2006/mkdocs-material

Material for Mkdocs 自定义Docker镜像文档

镜像概述

本镜像为基于Material for Mkdocs的自定义Docker镜像，集成了GitLab CI环境中常用的工具，旨在简化文档的构建、测试和部署流程，特别适用于GitLab CI/CD流水线中的自动化文档处理。

核心功能与特性

• Material for Mkdocs基础功能：提供Material Design风格的文档主题，支持响应式布局、搜索、导航等核心文档功能
• GitLab CI工具集成：内置GitLab CI环境中常用的文档处理工具，减少CI配置复杂度
• 环境一致性：确保本地开发与GitLab CI环境的构建结果一致，避免环境差异导致的问题
• 轻量级设计：在保留核心功能的前提下优化镜像体积，提升CI流水线执行效率

使用场景与适用范围

• GitLab CI/CD流水线：自动化执行文档构建、测试和部署任务
• 文档开发与预览：本地开发环境中快速预览文档效果
• 团队协作：为团队提供统一的文档构建环境，确保文档风格和构建流程一致
• 静态文档部署：配合CI/CD工具将构建后的静态文档部署到目标平台

使用方法与配置说明

前提条件

• 已安装Docker Engine（20.10+推荐）
• 熟悉Mkdocs项目结构及基本配置（mkdocs.yml）

基本使用（docker run）

本地开发预览文档：

bash
# 挂载当前Mkdocs项目目录并启动开发服务器
docker run -it --rm -v $(pwd):/docs -p 8000:8000 custom-mkdocs-image mkdocs serve --dev-addr=0.0.0.0:8000

构建静态文档：

bash
# 挂载项目目录并执行构建命令，输出到本地site目录
docker run -it --rm -v $(pwd):/docs custom-mkdocs-image mkdocs build

Docker Compose配置

创建docker-compose.yml文件：

yaml
version: '3.8'

services:
  mkdocs:
    image: custom-mkdocs-image
    volumes:
      - ./:/docs  # 挂载本地Mkdocs项目目录
    ports:
      - "8000:8000"  # 映射开发服务器端口
    command: mkdocs serve --dev-addr=0.0.0.0:8000  # 启动开发服务器

启动服务：

bash
docker-compose up

GitLab CI配置示例

在项目根目录创建.gitlab-ci.yml文件，配置CI流水线：

yaml
stages:
  - build-docs
  - deploy-docs

build-documentation:
  stage: build-docs
  image: custom-mkdocs-image
  script:
    - mkdocs build  # 构建静态文档
  artifacts:
    paths:
      - site/  # 保存构建产物，供后续部署阶段使用
    expire_in: 1 day  # 产物过期时间

deploy-documentation:
  stage: deploy-docs
  image: custom-mkdocs-image
  needs:
    - job: build-documentation
      artifacts: true
  script:
    # 根据实际部署需求配置部署命令，例如部署到GitLab Pages或其他静态服务器
    - echo "Deploying documentation to target platform"
  only:
    - main  # 仅在main分支触发部署

自定义配置

可通过挂载自定义mkdocs.yml文件覆盖默认配置：

bash
docker run -it --rm -v $(pwd)/mkdocs.yml:/docs/mkdocs.yml -v $(pwd)/docs:/docs/docs custom-mkdocs-image mkdocs build

注意事项

• 确保本地Mkdocs项目结构符合标准（包含mkdocs.yml配置文件和docs文档目录）
• CI环境中需确保Docker镜像拉取权限配置正确
• 构建大型文档项目时，建议适当调整CI流水线资源配置以提升构建效率