概述

其实我是想找一个文档管理的东西，无意间知道了mkdocs，感觉还不错，是使用python做的一个静态网站生成器

安装

安装很简单因为是使用python做的所以你要先安装python才可以，如果说安装python的最好的办法的话就是使用pyenv去安装，如果不会可以看我的这篇博客
fedora安装pyenv实现python的版本管理
python的版本是python2.7以上
现在我就当你安装好了python之后我们来安装mkdocs，一行命令搞定
pip install mkdocs
查看下mkdocs的版本

  ~ mkdocs --version
mkdocs, version 0.17.2

安装完成

生成自己的第一个网站项目

和hexo一样，我们要使用mkdocs命令去生成自己的第一个项目，使用下面的命令就可以完成

  ~ mkdocs new Yuncan-doc
INFO    -  Creating project directory: Yuncan-doc 
INFO    -  Writing config file: Yuncan-doc/mkdocs.yml 
INFO    -  Writing initial docs: Yuncan-doc/docs/index.md 

接着你会发现在当前目录下会生成一个以你工程名为名字的文件夹，目录结构是下面这样子的

  ~ tree Yuncan-doc 
Yuncan-doc
├── docs
│   └── index.md
└── mkdocs.yml

1 directory, 2 files

docs 下面放的是用markdown写的文档源文件
mkdocs.yml是mkdocs的配置文件
mkdocs有一个内置的server可以让你运行起来测试网站
就像下面这样子启动

  Yuncan-doc mkdocs serve
INFO    -  Building documentation... 
INFO    -  Cleaning site directory 
[I 171231 20:37:58 server:283] Serving on http://127.0.0.1:8000
[I 171231 20:37:58 handlers:60] Start watching changes
[I 171231 20:37:58 handlers:62] Start detecting changes

之后在本地浏览器输入http://127.0.0.1:8000来访问
这个服务器支持实时显示，怎么说呢就是当你改变配置文件或者文档中的内容之后，他的浏览器中的内容也会实时同步

新建一个页面

一个静态的网站不可能只有一个页面，所以我们现在就新建一个页面，首先在docs下面新建一个markdown文件，比如about.md用来描述这个网站是用来干什么的
touch docs/about.md
添加一些文字在这个文件里面，比如
### 这个网站是用来管理文档的
接着修改你的配置文件，也就是mkdocs.yml文件
变成下面这个样子

site_name: 云璨云市场文档
pages:
    - Home: index.md
    - About: about.md

修改主题

说实在的我是真的不喜欢默认的主题，那么现在我们来使用readthedocs主题吧
在配置文件里写入下面这一行
theme: readthedocs
之后主题就修改好了
推荐一个主题Windmill
地址
https://github.com/gristlabs/mkdocs-windmill
详细的主题使用方法看文档，都说出来就没意思了，不会的可以联系我问我。

改变站点图标

这个图标就是浏览器tab上的图标，你可以选择不改，也可以修改，如果要修改可以这样做首先在docs文件夹里新建一个img文件夹
之后把图标放到里面去，重命名成favicon.ico就好

经验

如果你想把这个当做博客的话，那么你可以这样做，一个分类一个文件夹，然后主题要找好，我上面推荐的主题就不错，还有pages这个属性可以不用写，不然新上一篇文章写一个，太累了，之后默认貌似是不支持搜索中文的，这个你可以看下面这个网址
https://cyent.github.io/markdown-with-mkdocs-material/appendix/search/
还有很多细节，慢慢优化了。不过说到底这个是用来管理文档的，不适合用来管理博客，博客还是hexo了

build

如果我们写完文章也配置完成之后，那么我们就要去生成一个静态网站了，这个很简单，一个命令搞定
mkdocs build

  Yuncan-doc mkdocs build 
WARNING -  Config value: 'theme_dir'. Warning: The configuration option {0} has been deprecated and will be removed in a future release of MkDocs. 
INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /home/bboysoul/Yuncan-doc/site 

上面这个警告的意思是你指定主题文件夹的参数不对,不用理他，
接着site文件夹中的内容就是你的静态网站

部署

部署我们可以使用readthedocs也可以使用githubpage，因为我的github上已经有我的博客了，所以就使用readthedoc了，注册readthedoc的账号，网址在下面
https://readthedocs.org/
我觉得这个就是一个持续集成的工具，不过mkdocs的主题一定要是readthedocs，你可以设置cname来使用自己的域名

欢迎关注Bboysoul的博客www.bboysoul.com
Have Fun