使用mkdocs管理你的博客或者文档

概述

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

安装

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

1
2
➜  ~ mkdocs --version
mkdocs, version 0.17.2

安装完成

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

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

1
2
3
4
➜  ~ 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 

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

1
2
3
4
5
6
7
➜  ~ tree Yuncan-doc 
Yuncan-doc
├── docs
│   └── index.md
└── mkdocs.yml

1 directory, 2 files

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

1
2
3
4
5
6
➜  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文件 变成下面这个样子

1
2
3
4
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

1
2
3
4
➜  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来使用自己的域名

欢迎关注我的博客 www.bboy.app Have Fun