minidocks/mkdocs

MkDocs Docker镜像文档

镜像概述和主要用途

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

核心功能和特性

预安装主题

• Material Design主题：遵循Google Material Design设计规范的现代响应式主题（https://squidfunk.github.io/mkdocs-material/）。
• Alabaster主题：视觉简洁、响应式、可配置的主题（Alabaster theme）。
• KPN Theme：KPN定制主题（https://kpn.github.io/mkdocs-kpn-theme/）。

预安装插件

通用插件

• Absolute to relative link：将绝对链接转换为相对链接（https://github.com/sander76/mkdocs-abs-rel-plugin）。
• Add number：自动为每个Markdown页面的标题（h1-h6）和导航编号（https://github.com/ignorantshr/mkdocs-add-number-plugin）。
• Autolinks：简化文档间的相对链接（https://github.com/midnightprioriem/mkdocs-autolinks-plugin/）。
• Autorefs：自动跨页面链接（https://github.com/mkdocstrings/autorefs）。
• Awesome Pages plugin：无需在mkdocs.yml中配置完整结构即可自定义导航（https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin）。
• Exclude：使用Unix风格通配符或正则表达式排除文件（https://github.com/apenwarr/mkdocs-exclude）。
• Categories：支持每页多分类并生成分类索引页（https://github.com/EddyLuten/mkdocs-categories-plugin）。
• Gallery：图片画廊功能（https://smarie.github.io/mkdocs-gallery/）。
• Gen files：构建时程序化生成文档页面（https://oprypin.github.io/mkdocs-gen-files/）。
• Git authors：显示Git作者信息（https://github.com/timvink/mkdocs-git-authors-plugin）。
• Git committers：显示Git提交者信息（https://github.com/ojacques/mkdocs-git-committers-plugin-2）。
• Git revision date：显示Git修订日期（https://github.com/timvink/mkdocs-git-revision-date-localized-plugin）。
• Merge plugin：合并多个MkDocs站点为一个主站点的子站点（https://github.com/ovasquez/mkdocs-merge）。
• Enumerate headings：跨站点页面自动编号标题（h1-h6）（https://github.com/timvink/mkdocs-enumerate-headings-plugin）。
• Img2Fig：将<img>转换为<figure>标签（https://github.com/stuebersystems/mkdocs-img2fig-plugin）。
• Kroki：集成Kroki生成图表（https://github.com/AVATEAM-IT-SYSTEMHAUS/mkdocs-kroki-plugin）。
• Literate Nav：使用Markdown而非YAML指定导航（https://oprypin.github.io/mkdocs-literate-nav/）。
• Macros：将Markdown页面转换为支持变量、宏和自定义过滤器的Jinja2模板（https://github.com/fralau/mkdocs_macros_plugin）。
• Markdown extra data：将mkdocs.yml中的extra变量注入Markdown模板（https://github.com/rosscdh/mkdocs-markdownextradata-plugin）。
• Minify：压缩HTML和/或JS文件（https://github.com/byrnereese/mkdocs-minify-plugin）。
• Mkdocstrings：从源代码自动生成文档（https://mkdocstrings.github.io/）。
• Mkdocs with Confluence：通过Confluence REST API上传Markdown文档到Confluence（https://github.com/pawelsikora/mkdocs-with-confluence/）。
• Monorepo：在单个MkDocs中构建多个文档，适用于大型代码库（https://github.com/spotify/mkdocs-monorepo-plugin）。
• Multirepo：将多个仓库的文档构建为一个站点（https://github.com/jdoiro3/mkdocs-multirepo-plugin）。
• Nav weight：以更Markdown化的方式组织导航（https://github.com/shu307/mkdocs-nav-weight）。
• Neoterot plugins：Neoterot开发的插件集合（Neoterot plugins）。
• No sitemap：禁用站点地图生成（https://github.com/leonardehrenfried/mkdocs-no-sitemap-plugin）。
• Print site：添加合并所有页面的打印页，支持导出为PDF（https://timvink.github.io/mkdocs-print-site-plugin/index.html）。
• Publisher：发布相关功能（https://mkusz.github.io/mkdocs-publisher/）。
• Pymdownx Material Extras：Material主题的额外扩展（https://github.com/facelessuser/mkdocs_pymdownx_material_extras）。
• Safe text：安全文本编辑支持（https://github.com/raimon49/mkdocs-safe-text-plugin）。
• Same dir：允许mkdocs.yml与文档放在同一目录（https://oprypin.github.io/mkdocs-same-dir/）。
• Simple hooks：自定义MkDocs钩子（https://github.com/aklajnert/mkdocs-simple-hooks）。
• Simple：从仓库中分散的Markdown文件构建文档（Simple）。
• Swagger UI：集成Swagger UI（https://blueswen.github.io/mkdocs-swagger-ui-tag/）。
• Redirects：创建页面重定向（https://github.com/datarobot/mkdocs-redirects）。

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

• PDF export：使用WeasyPrint将所有Markdown页面导出为PDF文件（https://github.com/zhaoterryy/mkdocs-pdf-export-plugin）。
• PDF generate：从MkDocs仓库生成单个PDF文件（https://github.com/orzih/mkdocs-with-pdf）。

Markdown扩展

• Customblocks：支持可参数化和可嵌套的自定义组件标记（https://github.com/vokimon/markdown-customblocks）。
• Include：允许包含其他Markdown文档内容（https://github.com/cmacmackin/markdown-include/）。
• Pygments：通用语法高亮工具（Pygments）。
• PyMdown Extensions：Python Markdown的扩展集合（https://facelessuser.github.io/pymdown-extensions/）。
• Mdx Truly Sane Lists：优化列表缩进和换行（https://github.com/radude/mdx_truly_sane_lists）。
• Breakless Lists Markdown Extension：无需在列表上方换行即可使用列表（https://github.com/adamb70/mdx-breakless-lists）。

使用场景和适用范围

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

使用方法和配置说明

创建新项目

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

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

启动文档服务器

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

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

标签

相关镜像

• https://github.com/minidocks/sphinx-doc

替代方案

• https://github.com/raspberryvalley/docker-mkdocs
• https://github.com/pozgo/docker-mkdocs
• https://github.com/squidfunk/mkdocs-material