buvis/mkdocs-git-sync

MkDocs Git Sync 镜像文档

镜像概述

该镜像用于在Docker环境中构建MkDocs站点，并实现从源Git仓库自动同步内容的功能。它仅负责将站点构建到容器的/app/site目录，需配合Nginx等Web服务器提供站点访问服务。

核心功能

• 在Docker中自动化构建MkDocs站点
• 定期从指定Git仓库拉取最新内容并更新站点
• 支持自定义MkDocs配置和Python依赖管理
• 通过Docker卷与Web服务器共享构建结果

使用场景

适用于需要基于Git仓库管理文档内容，并希望实现自动更新的MkDocs站点场景，如项目技术文档、产品手册、个人知识库等。

使用方法

前提条件

• 已安装Docker和Docker Compose
• 具备Git仓库访问权限（公开仓库直接访问，私有仓库需提供凭证）

部署步骤

1. 创建docker-compose.yml文件

yaml
version: '3'

services:
  syncer:
    image: docker.xuanyuan.run/buvis/mkdocs-git-sync
    environment:
      - GIT_REPO=https://github.com/buvis/mkdocs-zettelkasten.git
      - GIT_BRANCH=main
      - UPDATE_INTERVAL=60
    volumes:
      - ./config/syncer:/app/config
      - site:/app/site
  nginx:
    image: docker.xuanyuan.run/nginx
    ports:
      - 8000:80
    volumes:
      - ./config/nginx:/etc/nginx/conf.d
      - site:/site
    depends_on:
      - syncer
volumes:
  site:

2. 复制配置文件

将配置文件从 https://github.com/buvis/container-images/tree/main/apps/mkdocs-git-sync/config 复制到本地config目录。

3. 启动服务

bash
docker-compose up

访问站点

服务启动后，通过 [***] 访问构建的MkDocs站点。

配置说明

文件配置

• MkDocs配置文件：将mkdocs.yml挂载到容器内/app/config/mkdocs.yml，用于自定义MkDocs站点配置，具体配置方法参考 https://www.mkdocs.org/user-guide/configuration/%E3%80%82

• Python依赖文件：将requirements.txt挂载到容器内/app/config/requirements.txt，用于指定MkDocs所需的Python依赖，格式参考 https://pip.pypa.io/en/latest/reference/requirements-file-format/%E3%80%82

环境变量

• GIT_CREDENTIALS：访问私有仓库时使用，格式为<用户名>:<密码>或<token名称>:<token>
• GIT_REPO：必填，MkDocs源文件所在的Git仓库地址
• GIT_BRANCH：仓库分支，默认值为main
• UPDATE_INTERVAL：仓库拉取间隔（秒），默认值为900（15分钟）
• LOG_LEVEL：日志级别，参考 https://docs.python.org/3/library/logging.html#logging-levels%EF%BC%8C%E9%BB%98%E8%AE%A4%E5%80%BC%E4%B8%BA%60INFO%60