开始¶

Material for MkDocs是MkDocs之上的一个强大的文档框架，用于项目文档的静态站点生成器。¹如果你熟悉 Python，你可以用pip安装MkDocs的Material，Python 包管理器。如果没有，我们建议使用docker。

安装¶

Material for MkDocs以Python package的形式发布，可以安装 pip，理想情况下是通过使用virtual environment。打开终端并安装 Material for MkDocs，包括：

Latest9.x

pip install mkdocs-material

pip install mkdocs-material=="9.*" # (1)!

这将自动安装所有依赖项的兼容版本： MkDocs, Markdown, Pygments和Python Markdown Extensions。Material for MkDocs 始终致力于支持最新版本，因此没有必要单独安装这些软件包。

How to set up Material for MkDocs by @james-willett – 27m – 了解如何使用Material for MkDocs创建和托管文档网站 GitHub Pages上的分步指南。

Tip

如果你之前没有Python的经验，我们建议你阅读 Using Python's pip to Manage Your Projects' Dependencies，这是一个对Python包管理机制和帮助您在遇到错误时进行故障排除。

官方的Docker image是一个很好的启动和运行方式分钟，因为它预装了所有依赖项。打开终端并使用以下命令拉取图像：

Latest9.x

docker pull squidfunk/mkdocs-material

docker pull squidfunk/mkdocs-material:9

mkdocs可执行文件作为入口点提供，serve是默认命令。如果你不熟悉Docker，别担心，我们有你将在以下章节中介绍。

以下插件与Docker镜像捆绑在一起：

Warning

Docker容器仅用于本地预览目的不适合部署。这是因为使用的web服务器用于实时预览的MkDocs不是为生产使用而设计的，可能具有安全漏洞。

如何向Docker镜像添加插件？

Material for MkDocs仅捆绑选定的插件以保持大小官方形象较小。如果您要使用的插件未包含在内，您可以轻松添加它们：

Material for MkDocsInsiders

创建一个Dockerfile并扩展官方镜像：

Dockerfile

FROM squidfunk/mkdocs-material
RUN pip install mkdocs-macros-plugin
RUN pip install mkdocs-glightbox

Clone or fork Insiders存储库，并创建一个名为 user-requirements.txt存储库根目录中。然后，添加应安装到文件中的插件，例如：

user-requirements.txt

mkdocs-macros-plugin
mkdocs-glightbox

接下来，使用以下命令构建映像：

docker build -t squidfunk/mkdocs-material .

新映像将安装其他软件包，可以使用就像官方形象一样。

Material for MkDocs 可以通过克隆直接从GitHub使用将存储库放入项目根目录的子文件夹中，如果您想要使用最新版本：

git clone https://github.com/squidfunk/mkdocs-material.git

接下来，使用以下命令安装主题及其依赖项：

pip install -e mkdocs-material

2016年，Material for MkDocs开始是一个简单的MkDocs主题，但在几年的时间里，现在的情况远不止如此—— 许多内置插件、设置和无数自定义功能， Material for MkDocs现在是最简单、最强大的框架之一为您的项目创建文档。 ↩
请注意，现有功能的改进有时会发布为补丁发布，例如改进内容选项卡的呈现，如它们不被认为是新功能。 ↩