1. 前言

Material for MkDocs 是一个强大的文档框架，建立在 MkDocs 之上。MkDocs 是一个静态的项目文档生成器。如果你熟悉 Python，可以用 pip 安装 Material for MkDocs。如果不熟悉，建议使用 docker。

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

文档：Installation – Material for MkDocs

GitHub：squidfunk/mkdocs-material: Documentation that simply works

与hexo比较的话，简单点说就是：hexo是博客系统，MkDocs是文档系统。与hexo一样，推荐直接部署在自己的电脑上，方便后续调试与写作。

项目	Hexo	MkDocs
主要用途	博客、个人站点	文档站、手册、Wiki
用户群体	博主、写文章的人	开发者、项目文档作者
Markdown 支持	✔️	✔️（更偏文档格式，如导航、章节结构更友好）
多语言支持	✔️ 有插件	✔️ Material 主题内置部分支持

这篇文章中，夜梦使用python进行演示。

2. 准备

GitHub账号。

在开始部署之前，你需要在电脑上安装 python。下载Welcome to Python.org后安装（记得勾选add to path）。

安装完毕后，我们创建并激活虚拟环境，在虚拟环境中运行mkdocs（建议将%USERPROFILE%修改成你想要存放mkdocs的路径，你也可以直接在目标文件夹中运行注释的代码）

python -m venv %USERPROFILE%\mkdocs-venv
# python -m venv mkdocs-venv
%USERPROFILE%\mkdocs-venv\Scripts\activate.bat
# mkdocs-venv\Scripts\activate.bat

激活后命令行前面应该出现 (mkdocs-venv) 字样，像下面这样：

(mkdocs-venv) C:\%USERPROFILE%\mkdocs>

准备完成后，我们开始安装mkdocs。

3. 部署

安装mkdocs：

pip install mkdocs-material

4. 使用

安装完成后，在终端中输入mkdocs可以查看各个命令以及它们的使用方法。

Usage: mkdocs [OPTIONS] COMMAND [ARGS]...

  MkDocs - Project documentation with Markdown.

Options:
  -V, --version         Show the version and exit.
  -q, --quiet           Silence warnings
  -v, --verbose         Enable verbose output
  --color / --no-color  Force enable or disable color and wrapping for the output. Default is auto-detect.
  -h, --help            Show this message and exit.

Commands:
  build      Build the MkDocs documentation.
  get-deps   Show required PyPI packages inferred from plugins in mkdocs.yml.
  gh-deploy  Deploy your documentation to GitHub Pages.
  new        Create a new MkDocs project.
  serve      Run the builtin development server.

进入你mkdocs的安装目录，输入：

mkdocs new .

创建配置文件，完成后会提示：

INFO    -  Writing config file: ./mkdocs.yml
INFO    -  Writing initial docs: ./docs/index.md

你只需修改、设置 mkdocs.yml 的 site_name 以及添加几行，即可启用主题。

site_name: YeMengStar site
site_url: https://mkdocs.yemengstar.top/mysite
theme:
  name: material

预览/启动：

mkdocs serve

INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.37 seconds
INFO    -  [15:50:32] Serving on http://127.0.0.1:8000/mysite/

如果没有问题，你可以访问http://127.0.0.1:8000/mysite/进入页面：

编辑完成后，您可以使用以下命令从 Markdown 文件构建静态网站

mkdocs build

预览/启动方式和前面一样。

5. 发布到GitHub

待更新（夜梦会新开一篇文章讲讲怎么把这个发布到GitHub pages上~）