谈一谈|MkDocs介绍及应用

欢迎点击「算法与编程之美」↑关注我们！

本文首发于微信公众号："算法与编程之美"，欢迎关注，及时了解更多此系列文章。

欢迎加入团队圈子！与作者面对面！直接点击！

1 什么是MkDocs

MkDocs---markdown项目文档工具，是一个用来创建项目文档的快速、简单、完美的静态站点生成器，文档源码使用Markdown来撰写，用一个yml文件作为配置文档。它具有如下几个优点：

1.1 任意托管

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

1.2 大量主题

默认包含大量美观的主题。可以从 bootstrap, readthedocs 和 12 款 bootswatch 主题中选择。

1.3 即时预览

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

1.4 易于配置

可以配置文档主题。

1.5 交叉索引

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

 

2 什么是Materialfor MkDocs

一个MkDocs的MaterialDesign主题。(A Material Design theme for MkDocs )Material 是MkDocs的主题，是针对项目文档的优秀静态网点生成器。它是基于Google的Material Design 指南搭建的。

 

3 安装

因为mkdocs是基于python对markdown的文档生成器，安装mkdocs之前得先安装python。

3.1Mkdocs安装

pip install mkdocs

3.2Material for MkDocs安装

pip install mkdocs-material

3.3环境配置

要在cmd上运行mkdocs还需要配置系统环境，控制面板-集团和安全-系统-高级系统设置-系统变量，找到path，添加mkdocs.exe的路径。其路径根据安装方法不同位置不同，pip安装的是在python安装目录下的scripts下。最后以管理员身份打开cmd，输入mkdocs没报错就是安装成功了。

4 用mkdocs创建静态网页

4.1项目创建

管理员模式打开cmd，输入

mkdocs new my-project cd my-project mkdocs serve

生成一个my-project项目文件夹，里面有docs文件夹和mkdocs.yml配置文件，会给你一个预览网址默认是http://127.0.0.1:8000/，用默认浏览器打开它就可以看见网页。

4.2网页内容配置

因为mkdocs的即时预览，你修改的配置会直接载入网页。

用管理员模式下的cmd打开mkdocs.yml进行修改

site_name: MkDocs介绍及应用           /(网页名称) nav:                                  /(添加次级目录)  -  Home: index.md                      /(主页)  -  Blog: mkdocs介绍.md                 /(其他页面) theme:                                /(网页主题)  name: 'material'                       /(这就是我们安装的mkdocs-material)

在次级目录下还可以创建目录。

nav: -Blog： -Blog1:   xxx.md

网页内容就是放在docs文件下的.md文件。

配置完后在my-project文件夹下用cmd输入

mkdocs build

完成后会生成一个site文件夹，这个文件夹里的内容就是生成的静态网站。

5 结语

生成的静态网站可以部署到readthedoc和github上。团队可以用这个来管理博客和文档。因为不支持中文搜索，管理博客还是有一些问题的，主要还是用来管理文档的。

END

   实习主编   |   王楠岚

    责       编   |   王自强

 where2go 团队

---

   

微信号：算法与编程之美          

长按识别二维码关注我们!

温馨提示：点击页面右下角“写留言”发表评论，期待您的参与！期待您的转发！