melopt/mkdocs

Mkdocs.org镜像

该镜像允许在项目中使用mkdocs命令生成文档，集成了多种主题、插件及工具，简化文档构建流程。

核心功能

• 包含多种主题：mkdocs、readthedocs、alabaster、rtd-dropdown、bootstrap、cinder、material、nature
• 支持插件：MkDocs Merge（默认未激活，需在mkdocs.yml中配置）
• 集成Python Markdown扩展，可增强Markdown语法能力
• 提供Pygments代码高亮支持
• 支持多阶段构建，生成基于nginx的静态文档站点

使用场景

• 项目文档的快速生成与预览
• 静态文档站点的容器化部署
• 团队协作中的文档标准化构建

配置说明

快速开始

通过命令行获取使用说明：

bash
docker run -i --rm melopt/mkdocs

激活插件

需在项目的mkdocs.yml中添加插件配置，示例：

yaml
plugins:
  - mkdocs-merge

Markdown扩展配置

编辑mkdocs.yml添加扩展列表，示例：

yaml
markdown_extensions:
  - abbr
  - attr_list
  - def_list
  - footnotes
  - codehilite

Pygments代码高亮配置

1. 生成Pygments样式CSS（可在Dockerfile中添加）：

dockerfile
RUN mkdir /docs/docs/css && pygmentize -S default -f html -a .codehilite > /docs/docs/css/pygments.css

2. 在mkdocs.yml中加载CSS：

yaml
extra_css:
  - css/pygments.css

生成静态站点（多阶段构建）

使用以下Dockerfile构建静态文档站点：

dockerfile
FROM melopt/mkdocs AS builder
COPY <你的源文件> /docs/
RUN /usr/bin/generate_mkdocs_site

FROM melopt/nginx-alt
COPY --from=builder /build /usr/share/nginx/docs/