Skip to content

入门

¥Getting started

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

¥Material for MkDocs is a powerful documentation framework on top of MkDocs, a static site generator for project documentation.1 If you're familiar with Python, you can install Material for MkDocs with pip, the Python package manager. If not, we recommend using docker.

安装

¥Installation

建议使用 pip

¥with pip recommended

Material for MkDocs 已发布为Python 包，可以使用pip安装，最好使用虚拟环境。打开终端并使用以下命令安装 Material for MkDocs：

¥Material for MkDocs is published as a Python package and can be installed with pip, ideally by using a virtual environment. Open up a terminal and install Material for MkDocs with:

pip install mkdocs-material

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

  1. Material for MkDocs 使用语义版本控制2 ，因此最好将升级限制在当前主要版本。这将确保您不会意外升级到下一个主要版本，因为升级过程中可能会包含一些破坏您网站的重大更改。此外，您可以使用pip freeze创建锁定文件，以便始终可以重现构建：

    pip freeze > requirements.txt

    pip freeze > requirements.txt

    pip freeze > requirements.txt pip freeze > requirements.txt现在，锁文件可用于安装：

    pip install -r requirements.txt

    pip install -r requirements.txt

    pip install -r requirements.txt pip 安装 -r 要求.txt

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

¥Material for MkDocs uses semantic versioning2, which is why it's a good idea to limit upgrades to the current major version.

如何设置 MkDocs 的 Material by @james-willett – 27 分钟 – 通过分步指南了解如何使用 GitHub Pages 上的 Material for MkDocs 创建和托管文档站点。

¥This will make sure that you don't accidentally upgrade to the next major version, which may include breaking changes that silently corrupt your site. Additionally, you can use pip freeze to create a lockfile, so builds are reproducible at all times:

提示

¥Now, the lockfile can be used for installation:

如果您之前没有使用过 Python，我们建议您阅读使用 Python 的 pip 来管理项目的依赖项，这是对 Python 包管理机制的非常好的介绍，可以帮助您在遇到错误时进行故障排除。

¥This will automatically install compatible versions of all dependencies: MkDocs, Markdown, Pygments and Python Markdown Extensions. Material for MkDocs always strives to support the latest versions, so there's no need to install those packages separately.

使用docker

¥with docker

官方Docker 镜像是快速启动并运行的好方法，因为它预装了所有依赖项。打开终端并使用以下命令拉取镜像：

¥ How to set up Material for MkDocs by @james-willett – 27m – Learn how to create and host a documentation site using Material for MkDocs on GitHub Pages in a step-by-step guide.

docker pull squidfunk/mkdocs-material

docker pull squidfunk/mkdocs-material:9

mkdocs可执行文件作为入口点， serve是默认命令。如果您不熟悉 Docker，不用担心，我们将在以下部分中为您提供帮助。

¥Tip

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

¥If you don't have prior experience with Python, we recommend reading Using Python's pip to Manage Your Projects' Dependencies, which is a really good introduction on the mechanics of Python package management and helps you troubleshoot if you run into errors.

Warning

Docker 容器仅用于本地预览，不适用于部署。这是因为 MkDocs 用于实时预览的 Web 服务器并非为生产用途而设计，并且可能存在安全漏洞。

¥The official Docker image is a great way to get up and running in a few minutes, as it comes with all dependencies pre-installed. Open up a terminal and pull the image with:

How to add plugins to the Docker image?

Material for MkDocs 仅捆绑了部分插件，以保持官方镜像体积较小。如果您想要使用的插件未包含在内，您可以轻松添加：

¥The mkdocs executable is provided as an entry point and serve is the default command. If you're not familiar with Docker don't worry, we have you covered in the following sections.

创建Dockerfile并扩展官方镜像：

¥The following plugins are bundled with the Docker image:

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

克隆或 fork Insiders 仓库，并在仓库根目录下创建一个名为user-requirements.txt的文件。然后，将需要安装的插件添加到该文件中，例如：

¥The Docker container is intended for local previewing purposes only and is not suitable for deployment. This is because the web server used by MkDocs for live previews is not designed for production use and may have security vulnerabilities.

user-requirements.txt
mkdocs-macros-plugin
mkdocs-glightbox

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

¥Material for MkDocs only bundles selected plugins in order to keep the size of the official image small. If the plugin you want to use is not included, you can add them easily:

docker build -t squidfunk/mkdocs-material .

新的镜像将安装额外的软件包，并且可以像官方镜像一样使用。

¥Create a Dockerfile and extend the official image:

使用 git

¥with git

可以直接从GitHub使用 MkDocs 的材料，通过将存储库克隆到项目根目录的子文件夹中，如果您想使用最新版本，这可能会很有用：

¥Clone or fork the Insiders repository, and create a file called user-requirements.txt in the root of the repository. Then, add the plugins that should be installed to the file, e.g.:

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

接下来，安装主题及其依赖项：

¥Next, build the image with the following command:

pip install -e mkdocs-material

  1. 2016 年，Material for MkDocs 最初只是 MkDocs 的一个简单主题，但经过几年的发展，它现在已经远远不止于此——凭借众多内置插件、设置和无数自定义功能，Material for MkDocs 现已成为用于为您的项目创建文档的最简单、最强大的框架之一。↩

  2. 请注意，现有功能的改进有时会作为补丁版本发布，例如改进内容选项卡的渲染，因为它们不被视为新功能。↩