polinux/mkdocs

MkDocs Docker镜像

镜像概述和主要用途

本镜像基于Alpine Linux构建，集成了MkDocs静态站点生成器。MkDocs是一款快速、简单且美观的静态站点生成器，专为项目文档构建设计，文档源文件采用Markdown编写，通过单个YAML配置文件进行配置。该镜像旨在简化MkDocs的部署流程，利用Alpine Linux的特性实现极小的镜像体积（约25MB）。

核心功能和特性

• 轻量级基础：基于Alpine Linux，镜像体积小，资源占用低
• 实时重载：支持文档内容变更时自动刷新
• 模块扩展：可通过环境变量安装额外MkDocs插件
• 快速模式：仅重建变更或新增的文件，提升构建效率
• Git集成：支持从Git仓库拉取文档源，并可配置自动更新
• 灵活配置：通过环境变量自定义文档目录、服务地址、更新间隔等

使用场景和适用范围

• 需要快速部署MkDocs文档站点的开发团队
• 追求轻量级文档服务解决方案的项目
• 需要自动同步Git仓库中文档内容的场景
• 开发阶段需要实时预览文档变更的环境

使用方法和配置说明

Docker Compose配置示例

yaml
version: '3'

services:
  mkdocs:
    container_name: mkdocs
    image: polinux/mkdocs:1.1.2
    restart: always
    ports:
      - "8000:8000"
    environment:
      LIVE_RELOAD_SUPPORT: 'true'
      ADD_MODULES: 'fontawesome-markdown mkdocs-git-revision-date-localized-plugin mkdocs-material'
      FAST_MODE: 'true'
      DOCS_DIRECTORY: '/mkdocs'
      GIT_REPO: 'git@github.com:username/docs.git'
      UPDATE_INTERVAL: 15
      AUTO_UPDATE: 'true'
    volumes:
      - $HOME/.ssh/id_rsa:/root/.ssh/id_rsa

Docker Run命令示例

基础使用：

bash
docker run \
    -ti \
    --name mkdocs \
    polinux/mkdocs

带Git仓库和自定义配置：

bash
docker run \
    -ti \
    --name mkdocs \
    -p 80:9000 \
    -e "ADD_MODULES=mkdocs-bootstrap mkdocs-gitbook mkdocs-bootstrap4" \
    -e "LIVE_RELOAD_SUPPORT=true" \
    -e "FAST_MODE=true" \
    -e "DOCS_DIRECTORY=/my_docs" \
    -e "GIT_REPO=https://my_repos/custom-docs.git" \
    -e "GIT_BRANCH=develop" \
    -e "AUTO_UPDATE=true" \
    -e "UPDATE_INTERVAL=1" \
    -e "DEV_ADDR=0.0.0.0:9000" \
    -v ${HOME}/.ssh/id_rsa:/root/.ssh/id_rsa \
    polinux/mkdocs

环境变量说明

Git仓库文档更新方法

手动更新

假设容器名称为mkdocs：

bash
docker exec -ti mkdocs bootstrap update

执行后将显示类似以下输出：

Pulled branch: master
Commit: a4000c525f6db977777bf758987c4df0b44f59b4
Commit Message: Updated nodejs
Date: 2020-03-24 18:52:43
Author: Przemek Ozgo

自动更新

通过配置以下环境变量启用自动更新：

• AUTO_UPDATE=true：启用自动更新
• UPDATE_INTERVAL=15：设置更新间隔（分钟）

镜像构建

bash
docker build -t polinux/mkdocs .

故障排除

查看运行中的容器

bash
docker ps

查看容器日志

bash
docker logs mkdocs

进入容器shell

bash
docker exec -ti mkdocs /bin/bash

查看镜像历史和层大小

bash
docker history --no-trunc=true polinux/mkdocs | tr -s ' ' | tail -n+2 | awk -F " ago " '{print $2}'

作者

Przemyslaw Ozgo

许可证

https://app.fossa.io/api/projects/git%2Bgithub.com%2Fpozgo%2Fdocker-mkdocs.svg?type=large](https://app.fossa.io/projects/git%2Bgithub.com%2Fpozgo%2Fdocker-mkdocs?ref=badge_large)