MkDocs Docker镜像文档

!MkDocs Logo

镜像概述和主要用途

MkDocs 是一个快速、简单且美观的静态站点生成器，专门用于构建项目文档。文档源文件采用Markdown编写，通过单个YAML配置文件进行配置。本Docker镜像（minidocks/mkdocs）预安装了多种主题、插件和Markdown扩展，旨在提供开箱即用的文档构建体验，简化项目文档的创建流程。

核心功能和特性

预安装主题

• Material Design主题：遵循Google Material Design设计规范的现代响应式主题（Material Design theme）。
• Alabaster主题：视觉简洁、响应式、可配置的主题（Alabaster theme）。
• KPN Theme：KPN定制主题（KPN Theme）。

预安装插件

通用插件

• Absolute to relative link：将绝对链接转换为相对链接（Absolute to relative link）。
• Add number：自动为每个Markdown页面的标题（h1-h6）和导航编号（Add number）。
• Autolinks：简化文档间的相对链接（Autolinks）。
• Autorefs：自动跨页面链接（Autorefs）。
• Awesome Pages plugin：无需在mkdocs.yml中配置完整结构即可自定义导航（Awesome Pages plugin）。
• Exclude：使用Unix风格通配符或正则表达式排除文件（Exclude）。
• Categories：支持每页多分类并生成分类索引页（Categories）。
• Gallery：图片画廊功能（Gallery）。
• Gen files：构建时程序化生成文档页面（Gen files）。
• Git authors：显示Git作者信息（Git authors）。
• Git committers：显示Git提交者信息（Git committers）。
• Git revision date：显示Git修订日期（Git revision date）。
• Merge plugin：合并多个MkDocs站点为一个主站点的子站点（Merge plugin）。
• Enumerate headings：跨站点页面自动编号标题（h1-h6）（Enumerate headings）。
• Img2Fig：将<img>转换为<figure>标签（Img2Fig）。
• Kroki：集成Kroki生成图表（Kroki）。
• Literate Nav：使用Markdown而非YAML指定导航（Literate Nav）。
• Macros：将Markdown页面转换为支持变量、宏和自定义过滤器的Jinja2模板（Macros）。
• Markdown extra data：将mkdocs.yml中的extra变量注入Markdown模板（Markdown extra data）。
• Minify：压缩HTML和/或JS文件（Minify）。
• Mkdocstrings：从源代码自动生成文档（Mkdocstrings）。
• Mkdocs with Confluence：通过Confluence REST API上传Markdown文档到Confluence（Mkdocs with Confluence）。
• Monorepo：在单个MkDocs中构建多个文档，适用于大型代码库（Monorepo）。
• Multirepo：将多个仓库的文档构建为一个站点（Multirepo）。
• Nav weight：以更Markdown化的方式组织导航（Nav weight）。
• Neoterot plugins：Neoterot开发的插件集合（Neoterot plugins）。
• No sitemap：禁用站点地图生成（No sitemap）。
• Print site：添加合并所有页面的打印页，支持导出为PDF（Print site）。
• Publisher：发布相关功能（Publisher）。
• Pymdownx Material Extras：Material主题的额外扩展（Pymdownx Material Extras）。
• Safe text：安全文本编辑支持（Safe text）。
• Same dir：允许mkdocs.yml与文档放在同一目录（Same dir）。
• Simple hooks：自定义MkDocs钩子（Simple hooks）。
• Simple：从仓库中分散的Markdown文件构建文档（Simple）。
• Swagger UI：集成Swagger UI（Swagger UI）。
• Redirects：创建页面重定向（Redirects）。

仅在pdf和1-pdf标签中包含的插件

• PDF export：使用WeasyPrint将所有Markdown页面导出为PDF文件（PDF export）。
• PDF generate：从MkDocs仓库生成单个PDF文件（PDF generate）。

Markdown扩展

• Customblocks：支持可参数化和可嵌套的自定义组件标记（Customblocks）。
• Include：允许包含其他Markdown文档内容（Include）。
• Pygments：通用语法高亮工具（Pygments）。
• PyMdown Extensions：Python Markdown的扩展集合（PyMdown Extensions）。
• Mdx Truly Sane Lists：优化列表缩进和换行（Mdx Truly Sane Lists）。
• Breakless Lists Markdown Extension：无需在列表上方换行即可使用列表（Breakless Lists Markdown Extension）。

使用场景和适用范围

• 快速构建项目文档，需要美观的静态站点。
• 需要多样化主题选择（如Material Design、Alabaster等）。
• 需要丰富的插件功能，如自动编号、Git信息显示、导航自定义等。
• 需要将文档导出为PDF文件（使用pdf或1-pdf标签）。
• 管理多仓库或单仓库中的多个文档（使用Monorepo/Multirepo插件）。
• 需要将文档上传到Confluence（使用Mkdocs with Confluence插件）。

使用方法和配置说明

创建新项目

在当前目录下创建名为doc的文档项目：

bash
docker run --rm -v "`pwd`:/app" -w /app minidocks/mkdocs new doc

启动文档服务器

在doc目录中启动服务器，端口8000，使用Material Design主题：

bash
docker run --rm -v "`pwd`:/app" -w /app/doc -p 8000:8000 minidocks/mkdocs serve -a 0.0.0.0:8000 -t material

标签

相关镜像

• Sphinx

替代方案

• [***]
• [***]
• [***]