🚀 使用 Docker Compose 部署 MkDocs Material

🚀 使用 Docker Compose 部署 MkDocs Material

MkDocs Material 是一个基于 MkDocs 构建的美观且功能丰富的文档网站生成器。它使用 Material Design 设计语言，支持 Markdown、搜索、移动端适配、多语言等功能，非常适合快速创建技术文档、产品手册和教程等类型的网站。

📦 项目简介

• MkDocs Material 的核心优势在于将 Material Design 的优雅外观与 MkDocs 的简洁易用性完美结合。
• mkdocs-material 是基于 MkDocs（一款轻量级静态网站生成器）的现代化主题，专注于快速构建美观、易用的文档网站。它以 Markdown 为基础，无需复杂编程即可生成结构化的静态网页，适合个人或团队用于技术文档、知识库、教程手册等场景的展示与管理。

---

主要功能特点： - 🎨 美观的 Material Design 界面：提供现代化的用户界面，遵循 Google 的 Material Design 原则，提供多种主题配色和自定义选项。 - 📱 完全响应式设计：能够根据客户端浏览器页面尺寸自动缩放，对 PC 和移动设备都友好。 - 🔍 强大的搜索功能：内置全文搜索功能，并且支持中文搜索。 - 🌐 多语言支持：支持国际化，可以创建多语言文档站点。 - ⚙️ 丰富的扩展功能：支持插件机制，可以增加额外功能，例如代码高亮、数学公式、流程图等。 - 🚀 实时预览：内置开发服务器，支持实时预览文档修改。

核心特点：

1. 简洁美观：采用 Material Design 设计风格，界面清爽、响应式布局（适配手机、平板、电脑），支持深色 / 浅色模式切换。
2. Markdown 原生支持：直接使用 Markdown 语法编写文档，自动生成目录、导航栏，无需手动调整 HTML 结构。
3. 即时预览：启动服务后，修改 Markdown 文件会实时更新网页，方便边写边看效果。
4. 轻量易部署：生成的是纯静态文件（HTML/CSS/JS），可直接部署在任何服务器，Docker 化部署更简单，资源占用极低（内存通常 < 100MB）。
5. 功能丰富：支持代码高亮、数学公式、图表嵌入、搜索功能、多语言切换等，满足复杂文档需求。
6. 高度可定制：通过配置文件（mkdocs.yml）可自定义导航、主题颜色、logo、扩展插件等。

⚙️ 部署前准备

1. 环境要求

   • 已安装 Docker 和 Docker Compose。
   • 系统内存：建议 1GB 以上。
   • 确保服务器的 58000 端口（或您自定义的其他端口）未被占用。

2. 环境检查 在终端中执行以下命令，确认 Docker 环境正常： bash docker --version docker-compose --version

3. 创建项目目录 建议创建一个独立的目录来管理 MkDocs Material 的所有文件。 bash mkdir -p /opt/docker/mkdocs-material cd /opt/docker/mkdocs-material

🛠️ 配置 Docker Compose

基于您提供的配置，这里是对 docker-compose.yml 文件的解读和优化说明。

services:
  mkdocs-material:
    container_name: mkdocs  # 容器名称，便于管理
    volumes:
      # 1. 本地文档与配置目录：主机 ./docs → 容器 /docs（可存放项目配置文件）
      - ./docs:/docs
      # 2. 实际文档目录：主机 /mnt/10t/.../nas＆docker篇 → 容器 /docs/my-project/docs（核心！Markdown文件存这里）
      - "/mnt/10t/file/webdav/0/ob/nas＆docker篇:/docs/my-project/docs"
      # 可选：如需添加更多文档目录，可按此格式添加（取消注释并修改路径）
      #- "/mnt/10t/file/webdav/0/ob/存档案:/docs/my-project/docs"
    restart: always  # 容器退出后自动重启（确保服务稳定运行）
    ports:
      - 58000:8000  # 容器退出后自动重启（确保服务稳定运行）
    working_dir: /docs/my-project # 容器内工作目录（MkDocs项目根目录）
    image: squidfunk/mkdocs-material # 官方镜像（稳定、更新及时）
    command: serve -a 0.0.0.0:8000  # 启动命令：以服务模式运行，监听所有网卡的8000端口
    deploy:
     resources:
       limits:  # 资源限制（防止占用过多服务器资源）
        cpus: '1.0'  # 限制CPU使用，可根据实际情况调整
        memory: 1G   # 限制内存使用，可根据实际情况调整

#VPS版配置
services:
  mkdocs-material:
    container_name: mkdocs
    volumes:
      - ./docs:/docs
      - "/home/compose/go_webdav/mnt/0/ob/nas＆docker篇:/docs/my-project/docs"
      #- "/mnt/10t/file/webdav/0/ob/nas＆docker篇:/docs/my-project/docs"
      #- "/mnt/10t/file/webdav/0/ob/存档案:/docs/my-project/docs"
    restart: always
    ports:
      - 58000:8000
    working_dir: /docs/my-project
    image: squidfunk/mkdocs-material
    command: serve -a 0.0.0.0:8000
    deploy:
     resources:
       limits:
        #cpus: '1'
        #memory: 1G
        cpus: '0.1'
        memory: 356M

关键配置说明：

配置项	说明与建议
image	使用官方镜像 squidfunk/mkdocs-material。
ports	"58000:8000" 将容器内的 8000 端口映射到主机的 58000 端口。您可以根据需要修改主机端口（前面的58000），但容器端口（后面的8000）请保持不变。
volumes	./docs:/docs 用于持久化存储您的文档项目。/mnt/10t/file/webdav/0/ob/nas＆docker篇:/docs/my-project/docs 将您现有的文档目录挂载到容器内。
working_dir	设置容器启动后的工作目录为 /docs/my-project。
command	serve -a 0.0.0.0:8000 启动 MkDocs 开发服务器，并允许所有 IP 访问。

注意：如果您计划将文档项目放在其他位置，请相应调整 volumes 和 working_dir 的配置。

🚀 启动与验证

1. 启动服务 在 docker-compose.yml 文件所在目录执行： bash docker-compose up -d 此命令会拉取镜像并在后台启动容器。

2. 检查服务状态 bash docker-compose ps 如果看到 mkdocs 容器的状态为 Up，说明服务已成功启动。

3. 查看实时日志（可选） 如果遇到问题，可以通过以下命令查看容器日志来排查： bash docker-compose logs -f mkdocs-material

4. 访问 Web 界面 打开浏览器，访问 http://你的服务器IP:58000。

   • 如果一切正常，你将看到 MkDocs Material 的默认界面或您的文档内容。

⚙️ 基础配置与使用

成功部署后，您可能需要初始化项目或开始编写文档。

1. 初始化新项目（可选） 如果这是新项目，您可以进入容器内部初始化项目结构： bash docker exec -it mkdocs mkdocs new . 这会在您的工作目录（/docs/my-project）中创建基本的 MkDocs 项目结构，包括 mkdocs.yml 配置文件和 docs 文档目录。

2. 基本项目结构 一个典型的 MkDocs 项目结构如下： my-project/ mkdocs.yml # 配置文件 docs/ index.md # 首页文档 about.md # 其他文档

3. 配置 mkdocs.yml mkdocs.yml 是 MkDocs 的核心配置文件，基本配置示例如下：

    site_name: 我的文档网站
    theme:
      name: material

    nav:
      - 首页: index.md
      - 关于: about.md

#自用

#site_name: My Docs
site_name: 刘见锐的文档网站  # 网站标题
#copyright: Copyright &copy; 2016 - 2025 <a href="http://{host}">china</a>.
#copyright: Copyright &copy; 2016 - 2025 Shi.
copyright: Copyright &copy; 2016 - 2025 JianYue.'这是"刘见锐"的博客文档'


theme: 
  name: 'material'  # 使用 material 主题
  #name: material  # 使用 material 主题
  #name: 'readthedocs' #切换后无变化，差评。
  palette:
    primary: orange  # 主题主色调（可选：red、blue、green等）orange橙
    accent: indigo   # 强调色


#nav:  # 自定义导航栏（默认自动生成，自定义更清晰）
  #- 首页: index.md
  #- Docker 基础: docker-basic.md
  #- NAS 部署: nas-deploy.md
  #- 关于: about.md

1. 使用提示框（Admonition） MkDocs Material 支持多种提示框，可以增强文档表现力： ```markdown !!! note "注意" 这是一个普通的提示框。

   ??? tip "可折叠提示" 这个提示框默认是折叠的。

   !!! warning "警告" 这是一个警告提示。 ```

🔒 维护与管理

• 服务管理：

  • 停止服务：docker-compose down
  • 重启服务：docker-compose restart
  • 查看服务状态：docker-compose ps

• 数据备份：

  • 定期备份您的 docker-compose.yml 文件以及通过 volumes 映射的所有文档目录。

• 版本更新： MkDocs Material 活跃更新，建议定期升级： bash # 进入 docker-compose.yml 所在目录 docker-compose down docker-compose pull # 拉取最新镜像 docker-compose up -d # 可选：清理无用镜像 docker image prune

• 可选：自动生成文档：

  • 目录下新建 mkdocs_auto_build.sh 文件
  • 添加执行权限 chmod +x /home/compose/mkdocs/mkdocs_auto_build.sh
  • 添加定时任务，添加以下内容（每天凌晨 2:00 执行） crontab -e
  • 输入 0 1 * * * /home/compose/mkdocs/mkdocs_auto_build.sh
  • 等隔天凌晨一点自动执行脚本重启mkdocs容器+生成文档。
  • 也可输入带重启容器的命令，每小时执行↓
  • 1 * * * /home/compose/mkdocs/mkdocs_auto_build.sh && docker-compose -f /home/compose/mkdocs/docker-compose.yml down && docker-compose -f /home/compose/mkdocs/docker-compose.yml up -d
  • 找不到文件？本文教程里面的项目目录在 '/opt/docker/mkdocs-material' 而我这个文档脚本的项目在 '/home/compose/mkdocs'，将/home...开头的目录换成/opt...的目录就行了。请自行理解。

#!/bin/bash
# 检查容器是否正在运行
if docker ps --format '{{.Names}}' | grep -q "^mkdocs$"; then
    docker exec mkdocs mkdocs build
    echo "$(date): mkdocs build 执行成功" >> /var/log/mkdocs_build.log
else
    echo "$(date): 错误：容器 'mkdocs' 未运行！" >> /var/log/mkdocs_build.log
fi
#添加执行权限
#chmod +x /home/compose/mkdocs/mkdocs_auto_build.sh
#添加定时任务，添加以下内容（每天凌晨 2:00 执行）
#crontab -e
#0 1 * * * /home/compose/mkdocs/mkdocs_auto_build.sh
#* 1 * * * /home/compose/mkdocs/mkdocs_auto_build.sh && docker-compose -f /home/compose/mkdocs/docker-compose.yml down && docker-compose -f /home/compose/mkdocs/docker-compose.yml up -d

#时间设置参考
#* * * * *  # 分钟(0-59) 小时(0-23) 日(1-31) 月(1-12) 星期(0-7)
#0 2 * * *   # 每天凌晨2点

🐛 常见问题排查

问题现象	可能原因与解决方法
无法访问 Web 界面	1. 检查防火墙/安全组是否放行了 58000 端口。 2. 确认容器是否正常运行：docker-compose ps。 3. 查看容器日志：docker-compose logs mkdocs-material。
页面显示 "Page not found"	1. 检查 volumes 映射的文档目录是否正确。 2. 确认 working_dir 设置是否正确。 3. 检查 mkdocs.yml 中的导航配置是否正确。
文件更改未生效	1. 确认已正确挂载文档目录到容器内。 2. MkDocs 开发服务器通常会自动检测更改并刷新页面。
插件兼容性问题	1. 某些插件可能存在版本兼容性问题。 2. 尝试固定插件版本或查找替代方案。

💡 提示：MkDocs Material 支持许多高级功能，如版本控制、多语言站点等，您可以在熟悉基本使用后进一步探索。

希望这份教程能帮助您顺利部署 MkDocs Material，开始创作精美的文档！