​前言​

大家好，我是大飞。

最近啊，我比较迷恋文档和静态站点生成，今天我们再分享一个基于 ​​Python​​​ 和 ​​Markdown​​​ 的文档生成器。它就是 ​​MkDocs​​。

​关于 MkDocs​

​​MkDocs​​​ 是一个快速、简单、完全华丽的静态站点生成器，用于构建项目文档。文档源文件以 ​​Markdown​​​ 格式编写，并使用单个 ​​YAML​​ 配置文件进行配置。

​呆猫​

​安装 MkDocs​

pip install mkdocs

​创建 MkDocs 项目​

PS C:\> mkdocs.exe new my-demo
INFO     -  Creating project directory: my-demo
INFO     -  Writing config file: my-demo\mkdocs.yml
INFO     -  Writing initial docs: my-demo\docs\index.md
PS C:\> cd .\my-demo\
PS C:\my-demo> ls


    目录: C:\my-demo


Mode                 LastWriteTime         Length Name
----                 -------------         ------ ----
d-----          22-2-9  下午 09:00                docs
-a----          22-2-9  下午 09:00             20 mkdocs.yml


PS C:\my-demo>

​启动项目​

命令：​​mkdocs.exe serve​​

MKDocs墙裂推荐给你_下拉菜单启动过程MKDocs墙裂推荐给你_python_02文档首页预览效果

如上，我们可以发现两个亮点。第一 ​​MkDocs​​​ 生成的文档自带 ​​ico​​​；第二 ​​MkDocs​​ 默认支持搜索。

​打造我们自己的在线文档​

​​MkDocs​​​ 不同于 ​​Pelican​​​ 等站点生成器，其类似 ​​Docsify+Pelican​​​，既可以在访问过程中动态渲染，也可以编译为静态资源。我们只需要维护自己的 ​​docs​​ 目录即可。

​创建自己的文档​

我们在 ​​docs​​​ 目录下创建我们自己的文档​​mydemo.md​​，内容太长，就不做展示了。

然后我们访问​​http://localhost:8000/​​​，就可以看到我们的站点已经发生了变化。没错，​​MkDocs​​ 是支持热加载的。

MKDocs墙裂推荐给你_下拉菜单_03新效果MKDocs墙裂推荐给你_生成器_04我自己的文档

​下拉菜单​

我们需要在​​mkdocs.yml​​​中进行 ​​nav​​​ 配置，假设我们想把我们的文章 ​​Mydemo​​​ 放到一个 ​​Blog​​​ 下拉菜单中，起名为 ​​Pelican​​ 入门。

site_name: My Docs
nav:
    - Home: '../'
    - 'Blog':
      - 'Pelican入门': 'mydemo.md'

再次查看​​http://localhost:8000/​​

MKDocs墙裂推荐给你_下拉菜单_05下拉菜单效果

不得不说，秒啊。

​编译文档​

mkdos.exe build

MKDocs墙裂推荐给你_python_06编译结果

我们进入 ​​site​​​ 目录，用 ​​python​​​ 的 ​​http.server​​ 模块启动我们能的静态站点。

MKDocs墙裂推荐给你_下拉菜单_07启动站点MKDocs墙裂推荐给你_下拉菜单_08页面效果

为了方便展示，我们直接使用 ​​python​​​ 的 ​​http.server​​​ 工具启动了我们的站点，实际生产中建议你选择 ​​nginx​​​ 之类的 ​​web​​ 服务器来托管你的静态站点。

更多内容详见：https://www.mkdocs.org/


MKDocs墙裂推荐给你_下拉菜单_09

END