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

其实我是想找一个文档管理的东西,无意间知道了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

稿源:Bboysoul (源链) | 关于 | 阅读提示

本站遵循[CC BY-NC-SA 4.0]。如您有版权、意见投诉等问题,请通过eMail联系我们处理。
酷辣虫 » 综合编程 » 使用mkdocs管理你的博客或者文档

喜欢 (0)or分享给?

专业 x 专注 x 聚合 x 分享 CC BY-NC-SA 4.0

使用声明 | 英豪名录