使用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

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏古时的风筝

django开发个人简易Blog—nginx+uwsgin+django1.6+mysql 部署到CentOS6.5

前面说完了此项目的创建及数据模型设计的过程。如果未看过,可以到这里查看,并且项目源码已经放大到github上,可以去这里下载。 代码也已经部署到sina sea...

2879
来自专栏月牙寂

docker源码分析(2)---docker server

第一时间获取文章,可以关注本人公众号 月牙寂道长 yueyajidaozhang

3346
来自专栏后端之路

idea svn 使用方法(Merge)

目前项目中使用idea作为主要的开发工具。 部分同学在操作idea的vcs总是会出现一些问题,现将使用步骤说明如下: idea虽然自带svn插件,但是仍然是调用...

2867
来自专栏Jerry的SAP技术分享

如何证明CRM WebClient UI上的应用是有状态(Stateful)的

随便找一个在CRM WebClient UI里会被频繁调用到的函数,在函数里创建一个隐式增强,打印当前的会话ID。

3535
来自专栏维C果糖

Git 的安装流程及步骤

在之前的「史上最简单的 GitHub 教程」中,我们已经知道了如何创建 GitHub 账号、创建仓库、进行个性化设置等等,但是我们还要知道:GitHub 是基于...

2457
来自专栏SpringBoot 核心技术

第十五章:使用SpringBoot validator让数据更真实

1573
来自专栏挖坑填坑

使用Ionic3创建原生app系统入门

地址:https://services.gradle.org/distributions/

1084
来自专栏从零开始学自动化测试

appium+python自动化53-adb logcat查看日志

做app测试,遇到异常情况,查看日志是必不可少的,日志如何输出到手机sdcard和电脑的目录呢?这就需要用logcat输出日志了 以下操作是基于windows平...

1932
来自专栏李蔚蓬的专栏

关于Android Studio中Run按钮是灰色的解决

今天导入一个别人的项目,在导入之前是老方法,覆盖  了三个关键文件之后(.gradle文件夹的内容版本若与本地不一,也应删掉),重启AS;

1.9K2
来自专栏Java架构沉思录

一文读懂 HTTP 2.0 之服务器推送

原文:http://www.ruanyifeng.com/blog/2018/03/http2_server_push.html

1031

扫码关注云+社区