Mkdocs功能介绍

简单而言,Mkdocs是一款开源,免费的文档制作工具.可以用来编辑制作各类结构化文档,并方便的发布对应的静态html项目,直接部署在服务器上进行查看.

包括产品说明书,接口文档,开发日志等形式的专用文档都可以使用Mkdocs进行维护.

同时,Mkdocs还能够方便的组织其他软件所生成的HTML类型的独立文档,如Axure RP所生成的原型文档,StarUML生成的图文档等等.

与其他专用的文档工具不同,Mkdocs的优势在于文件的组织管理,属于通用性工具,以文字编辑能力见长.适合作为所有文档的统一入口.

安装

Mkdocs依赖Python,无论在windows或者mac平台都可以进行安装.

截止目前,对于Python3.8还没有完全支持,在使用中会出现无法启动服务或者生成项目的问题.因此推荐使用Python的稳定2.7版本或者3.7.5.

python安装

首先在终端或者命令行中输入:python --version 如果显示结果为:Python 2.7.16 或者其他版本号则代表已经安装了python. 否则需要对python进行安装.

下载链接

v2.7: win_64_bit | mac_64-bit

v3.7.5: win_64_bit | mac_64_bit

下载完成后双击完成即可.

Mkdocs安装

相对简单,且社群维护的中文文档非常详细,再此不再赘述.通过中文文档链接查看即可.

其他版本文档

英文文档 | 官网

基本使用

为了节省时间,也作为个人知识整理,对mkdocs一些基本用法做一些梳理.

文件结构

Mkdocs本质上是对Markdown的解析,使其转化成为Html文件,并通过浏览器展示的工具.关于Markdown相关的内容本文不做展开,网络相关的内容太多,这里推荐一篇源于网络的Markdown教程.

每一个md文件都会在构建静态站点的时候被自动转成html页面,因此我们不必再关注任何的代码,只需要关注具体的文本内容,做好编辑,然后自动转化项目即可.

在Mkdocs项目的文件夹中默认包含一个docs文件夹,一个mkdocs.yml文件.

前者用来统一管理整个文档的所有资源,包括md文件,png图片文件,其他文件.并且docs文件夹将作为文档的根路径.所有文件都可以通过'/'来进行路径定位.

docs文件夹下可以根据需求随意建立文件夹,每个文件夹储存的文件类型不限,举例而言,在我的个人站点项目中的文件夹组织形式如下:

|docs
|----article
|----img
|----company
|----|----article
|----|----other_docs
|----|----img
|----|----gov
|----task
|----index.html

当然文件夹依然可以细分,在这里不做更多扩展.

根据这个目录结构,当article文件夹下的一个文件,比如教程.md希望使用docs/img这个目录下的图片1.png,那么就可以通过相对路径:../img/1.png来获取,也可以通过绝对路径:/img/1.png来获取.

其中..代表上一层目录. .则代表当前目录,如当前目录下的1.png文件可以写成./1.png,通常./可以直接省略,即可以直接简写成1.png.

但是需要注意,如果在一个md文件中希望建立项目内另一个md文件的链接,对链接方式会略有不同,比如:docs/article/目录下的文件topic.md中想要加入一个docs/company/article/目录下其他topic2.md文件的链接.

  • 通过相对路径链接,此时我们可以通过[topic2](../company/article/topic2.md)来完成.

    因为在md文件中的相对路径都是指没有进行静态网页编译时的原始目录结构,所以可以找到md源文件

  • 通过绝对路径链接,绝对路径则需要改为[topic2](/company/article/topic2)

    因为以"/"开头的绝对路径指的是静态页面编译后的根目录,所以已经不存在md文件了,但每一个md文件都会在原有目录结构的位置创建一个同名的文件夹,内部包含一个index.html文件,因此只需要简单的删除掉.md后缀,并在最开始加上"/"便可以了.事实上,完整的绝对路径应该是[topic2](/company/article/topic2/index.html).而我们只是利用了浏览器机制省略掉了最后的/index.html后缀.

配置文件

docs文件夹在一起的mkdocs.yml便是这个文档项目的配置文件.决定了Mkdocs将会如何解析docs下的文件结构,以及html文档的基本配置.通常较为常用的配置包含:

  • site_name: 站点的名字,将作为页面标题显示在浏览器上;
  • site_author: 站点作者,主要用于生成源数据,有利于SEO,观看价值不大.
  • copyright: 版权信息
  • nav: 页面导航配置的键值对.

更详细的配置文件参数可以在Mkdcos中文文档中查看.此处不再详细展开.

yml文件是YAML语言的对应文件格式,简单理解就是个 键值对配置文件,每一行代表一条数据,包含一个键和一个值,中间用冒号隔开. 也可参照网络教程做更加深入的了解.此处仅给出一个完整范例:


#  `mkdocs.yml`配置文件
#  以'#'开头代表对配置文件的注释,可以出现在任何地方,仅有说明作用,不对最终结果产生任何影响

nav:                    # 文档的导航栏配置
- index: 'index.md'     # 必须包含一个值为`index.md`的导航页,目的在于为网站生成默认入口,导航栏标题可以自拟.
- blog:                 # 一级导航菜单`blog`可以叫任何名字,用户自定,不对应任何具体的值
                        # 但是必须在`blog`之后紧跟一个冒号`:`,必须是英文,且冒号后需要有一个空格
                        # 不然会引起mkdocs的编译错误.
    - 'company' :       # 在blog菜单下的二级菜单,`company`
        - 'article':    # 同理
            # 具体的页面,页面标题为"article1",对应的md文件路径.
            # NOTE:对mkdocs.yml文件来说,默认当前目录是`/docs`,也就是与`index.md`在同一个目录下.
            - 'article1' : 'company/article/article1.md'            
            - 'article2' : 'company/article/article2.md'
        - 'information':
            - 'info1' : 'company/info/info1.md'
- other:
        - 'topic' : "some/path/sometopic.md"

### 站点的基本配置

site_name: Nestor's Workspace
site_url: http://www.nestor.me
site_author: Nestor
copyright: "copyright © 2019 <a href='mailto:admin@nestor.me'>Nestor</a> <br/>网站备案信息:鲁ICP备13008666号-1"

theme: readthedocs
# --------

基本命令

Mkdocs命令需要在终端中执行,即Mac系统下的terminal.app,或者Windows下的Command Line Tools,可以通过按下Windows键+R,输入cmd启动.

执行mkdocs时需要在项目文件夹中,即包含mkdocs.yml的文件夹路径下.

  • mkdocs new <name>:创建一个名为name的文件夹,作为项目目录,内部即为前文所说的文件结构;
  • mkdocs serve: 运行mkdocs服务,打开任何浏览器,输入127.0.0.1:8000即可访问文档页面.
  • mkdocs build: 构建静态项目,将在项目文件夹内生成一个site文件夹,内含全部文档页面.

servebuild命令可以通过添加-h后缀查看命令帮助,后缀需要用空格隔开. 也可以通过官方文档查看更详细的命令用法.

编辑器工具

当搞定了mkdocs的安装,基本的使用命令,文件结构,Markdown语法,那么便已经具备了跟功能相关的全部知识了.虽然用记事本就可以实现对md文件的编辑,但毕竟还是有免费且专业的工具来帮助我们更高效的工作.不管你是否有自己爱用的md编辑器,我还是想要推荐一款开源,完全免费的软件: Brackets.其优点在于:

  • 能够固定打开一个目录,并直接在软件内维护目录内部结构,新建,删除,移动,重命名均可.因此直接打开docs便完全掌控了工作空间;

  • 独立工作区,任何打开并修改的文件会在工作区内独立显示,虽然mkdcos.yml不再docs目录下,不能通过路径结构直接浏览,但是却能在工作区中直接访问;

  • 对Markdown的完美支持,当然,几乎任何编辑器都能够做的到这一点;

  • 专注模式.除了文本编辑区以外的内容全部一键隐藏;

  • 免费.

What's next?

本文对Mkdocs工具进行了简单的介绍,读完本页基本上已经可以通过Mkdocs来进行基础文档的维护了. 在[Mkdocs进阶应用]一文中将重点介绍几个我自己的使用心得.