跳转至

MkDocs建站指南⚓︎

约 598 个字 21 行代码 预计阅读时间 2 分钟

主要来源资料

Material for MkDocs官方文档

MkDocs中文文档

为什么选择Mkdocs?⚓︎

核心优势

任意托管：Mkdocs可以构建完全的静态HTML站点，可以将它托管到GitHub pages等任意地方。

大量主题：默认包含大量美观的主题。

即时预览：内建的开发服务器使你在撰写文档的时候就即时预览。它甚至能在保存更改时自动载入，只需刷新浏览器就可以查看更改。

易于配置：可以配置文档主题。

交叉索引：使用MkDocs链接语法创建交叉索引。

MkDocs是一个用于创建项目文档的 快速，简单，完美华丽的静态站点生成器。文档源码使用 Markdown来撰写，用一个YAML文件作为配置文档。

环境准备⚓︎

需要Python和Python package manager pip来安装MkDocs。

可以通过以下 cmd 命令查看是否安装了上述依赖（可右键文件夹打开Git Bash进行操作）：

$ python --version
Python 3.13.5
$ pip --version
pip 25.2

若没有安装，请参考相关文档。安装完成后，使用pip安装mkdocs：

$ pip install mkdocs

运行mkdocs -h以检查是否正确安装。若安装成功，则会出现以下结果：

$ mkdocs -h
Usage: mkdocs [OPTIONS] COMMAND [ARGS]...
  MkDocs - Project documentation with Markdown.
Options:...
Commands:...

Mkdocs初始化（本地搭建）⚓︎

开始⚓︎

输入以下命令以开启一个新项目。

$ mkdocs new 你的项目名
$ cd 你的项目名

MkDocs包含了一个内建的服务器以预览当前文档。控制台切换当前目录到 mkdocs.yml 配置文件相同文件夹，输入 mkdocs serve 命令以启动内建服务器（可通过在mkdocs.yml中设置dev_addr进行修改）：

$ mkdocs serve
Running at: http://127.0.0.1:8001/ #以你的实际网址为准

在浏览器中打开 http://127.0.0.1:8001/ ，编辑 docs/index.md 文件并保存，刷新浏览器你将看到文档被同步更新。

站点生成⚓︎

通过以下命令生成文档。

$ mkdocs build

一段时间后，可能有文件被从源码中移除了，但是相关的文档仍残留在 site 目录中。在构建命令中添加 --clean 参数即可移除这些文档。

$ mkdocs build --clean

发布⚓︎

MkDocs生成的文档只包含静态文件，因此你可以将文档部署到任意地方。

Material主题搭建⚓︎

安装⚓︎

通过pip安装Material：

$ pip install mkdocs-material

配置⚓︎

只需在mkdocs.yml中添加以下即可启用主题。

theme: 
  name: material

发布网站⚓︎

设置Git存储库⚓︎

请将 repo_url 设置为存储库的公共 URL，例如：

repo_url: https://github.com/vigilux418/mkdocs

手动部署项目文档⚓︎

$ mkdocs gh-deploy --force

评论