基于Mkdocs和ReadTheDocs的文档网站的构建

学习心得,记录一下


事情发生的原因也实属偶然,昨天再看Sponge的教程时候,偶然间看到了它的文档网站制作精良,界面好看。又突然想起我前几天折腾太玄的lua教程文档时候的繁琐程度,加之不喜欢gitbook和github wiki的界面。于是决定尝试去好好研究下这个网站用的是什么框架构架的。

最后研究出结论:

能够免费构建markdown语法书写的文档?!这一下就打动了我,研究一番后写出这面简单的心得,分享给大家。

相关链接:

1.Mkdocs环境的构建

实际上,如果你的电脑操作系统是Windows的话,不推荐你了解这一部分。Windows下开发环境的构建一直为人所诟病,而且这个环境的搭建仅仅是方便实时调试用,只需要写好一个yml配置文件,导入ReadTheDocs网站,该网站会自动构建文档网页。所以费时费力去折腾环境搭建违背了本篇教程的本意。

但是你的电脑是Linux系统就另当别论了,只需要如下指令即可安装Mkdocs:

$ pip install mkdocs

需要注意这个框架是用Python写的,请务必保证你的Python的安装。

之后的常用指令只有这几个:

指令用途
mkdocs new构建一个新的mkdocs工程
mkdocs serve在本机构建出调试用的文档网页
mkdocs build在本机构建出实际可用的文档网页
mkdocs gh-deploy将你写的文档部署到github page

当我们构建了新的工程之后,工程结构也很简单,基本上是如下样子

.
├── docs
│   └── index.md
└── mkdocs.yml

mkdocs.yml文件是配置文件,到时候ReadTheDocs自动构建时候,也是是别的文件主目录下的这个配置文件。

docs文件夹是放置文档的地方,里面的index.md就是文件的索引了。

2.配置文件的书写

官方文档讲了一堆堆配置文件,我只挑一些重要的来说下,有一个pages相关配置死活有问题。

site_name: Mkdocs教程
theme: readthedocs
repo_url: https://github.com/TartaricAcid/Mkdocs
site_favicon: favicon.ico
copyright: 酒石酸的测试项目

来解释下每个配置啥意思,除了site_name是必须要有的,其他的都可选。

然后随意在你的docs文件夹下放置markdown文件吧,框架会很智能的将这个文件夹下所有的md文件均加载上去,并按照文件夹的排列整齐划一的排布,完全不用操心别的。

docs
   ├── about.md
   ├── index.md
   ├── 第一章
   │   ├── 第一节-如何开始.md
   │   └── 第二节-明白了吗.md
   └── 第二章
       ├── 第一节-这是什么.md
       ├── 第二节-咋开始啊.md
       └── 第三节-这么回事.md

除了index.mdabout.md命名是有限制的,其他都很随意。

3.使用ReadTheDocs自动构建文档网页

ReadTheDocs网站是免费网站,能够自动抓取github制定仓库的文件,自动构建出可以观看的网页,并且还主动给你分配一个域名来访问这个文档页面。

首先,申请一个ReadTheDocs账户,并将其与你的github账户连接。 pic

然后导入你的仓库 pic

然后进入你的工程界面,就是这个样子啦 pic 可以在右侧看到构建情况,以及自动分配的域名。

不过默认是用的Sphinx构建网页,我们得先调节一下配置,点击图中的Admin按钮,找到setting部分 pic

往下翻,调节这一处的Documention type即可(你还可以顺手调节下语言) pic

然后在工程主页找到给你的域名就能访问文档了,欢呼吧 pic

不过,有一件事需要注意,Mkdocs识别的markdown和我们github用的markdown有些不同的,具体咱可以看看这个教程,写的很详细: CommonMark官方说明文档