minidocks/mkdocs

MkDocs Docker镜像文档

!MkDocs Logo

镜像概述和主要用途

https://www.mkdocs.org/ 是一个快速、简单且美观的静态站点生成器，专门用于构建项目文档。文档源文件采用Markdown编写，通过单个YAML配置文件进行配置。本Docker镜像（https://hub.docker.com/r/minidocks/mkdocs%EF%BC%89%E9%A2%84%E5%AE%89%E8%A3%85%E4%BA%86%E5%A4%9A%E7%A7%8D%E4%B8%BB%E9%A2%98%E3%80%81%E6%8F%92%E4%BB%B6%E5%92%8CMarkdown%E6%89%A9%E5%B1%95%EF%BC%8C%E6%97%A8%E5%9C%A8%E6%8F%90%E4%BE%9B%E5%BC%80%E7%AE%B1%E5%8D%B3%E7%94%A8%E7%9A%84%E6%96%87%E6%A1%A3%E6%9E%84%E5%BB%BA%E4%BD%93%E9%AA%8C%EF%BC%8C%E7%AE%80%E5%8C%96%E9%A1%B9%E7%9B%AE%E6%96%87%E6%A1%A3%E7%9A%84%E5%88%9B%E5%BB%BA%E6%B5%81%E7%A8%8B%E3%80%82

核心功能和特性

预安装主题

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

预安装插件

通用插件

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

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

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

Markdown扩展

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

使用场景和适用范围

• 快速构建项目文档，需要美观的静态站点。
• 需要多样化主题选择（如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

标签

相关镜像

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

替代方案

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