使用 mkdocs 搭建博客和编写文档

平时比较懒,写的文章和羊拉屎一样,东一点,西一点,散落在各个平台。 一直想把所有的文章都放在一个统一的地方,可以起到备份作用,同时也希望有一个自己的窝。

以前也尝试用过 hexo 和 Hugo 这样的静态博客,搭配上主题还是非常舒服的。不过功能上偏向博客需求,如果想定制一些专题写作计划,实现起来比较麻烦。

经过一番折腾,决定把文章签到到文档生成器上,看起来会系统一些,当然也会存在一些问题,比如标签管理和编写时间的缺失。任何计划都有利有弊,还是先做一个出来再说。

选择 mkdocs 还是 sphinx

因为自己主要使用 python 语言,所以还是使用 python 开发的工具会比较有安全感,如果真遇到问题,至少可以通过源码去排查问题。python 其实也有 pelican 这样的静态博客生成器,使用起来也非常方便。在文档生成器上,主要有 2 个主流的:mkdocs 和 sphinx。

很多大佬写的框架都是 sphinx 编写的,比如 requests 库就是通过 sphinx 部署在 readthedocs 平台上。

mkdocs 用来会简单一些,而且越来越多的新框架使用 mkdocs 编写文档,像 web 开发框架 FastAPI。 看了一下 sphinx 和 mkdocs 的官方文档,mkdocs 会清晰一些, sphinx 看起来有点复杂。 又查看了 GitHub 上面两个库的 star 数,最后还是选择用 mkdocs。

安装 mkdocs

mkdocs 使用 python 语言编写,先要下载 python 环境,然后通过 pip 安装:

pip install mkdocs

接下来使用 mkdocs 命令进行操作,命令主要有 4 个:

  • build, 把 markdown 文档转成 html 页面,在网页中呈现的效果就是 build 之后的 html 文档;
  • gh-deploy, 部署文档到 GitHub Pages, 主要作用是把生成的 HTML 文档放到 gh-pages 分支当中,然后让 GitHub Pages 显示 gh-pages 分支当中 HTML 页面;
  • new 生成一个新的项目,其实就是创建一个 mkdocs.yml 的配置文件和 doc 目录存储 markdown 文件;
  • serve 运行服务器,通过自己的方式在本地或服务器部署,内部是使用 tornado 作为服务器运行。

先在任意目录下创建一个项目:

mkdocs new .

此时目录下会有一个 mkdocs.yml 文件和一个 docs/ 的子目录,子目录下面有一个 index.md 的文件。

image-20201204151701164

在 mkdocs 中写文章

docs/index.md 文件就是整个项目的首页,在本地开启服务:

mkdocs serve

通过浏览器访问 http://localhost:8000, 就可以看到 index.md 当中的内容了。

image-20201204152132584

如果有新的文章,直接在 docs 目录下创建 markdown 文件。需要创建专题或者分类,可以创建子文件夹,mkdocs 默认会把这些文件放到导航栏展示出来。

image-20201204153048450

修改主题

mkdocs 可以修改主题,改变页面的展示效果。 修改为内置主题只需要在 mkdocs.yml 文件中添加 theme 配置选项:

theme: 
  name: readthedocs

再次访问页面,网站的展示就变成了 readthedocs 样式了。readthedocs 主题是自带的,不需要额外安装。

image-20201204154033138

如果需要安装第三方的主题,先要安装才可以使用。我们来看一下 FastAPI 的文档主题 mkdocs material, 这个主题在 GitHub 上有 5.1k 的 star, 非常火爆。

首先通过 pip 安装:

pip install mkdocs-material

再配置 mkdocs.yml 文件, 就可以使用这个模板了。

theme: 
  name: material

mkdocs 也支持自定义主题。这里就不折腾了,感兴趣的可以自己查资料。

配置导航

mkdocs material 主题 默认是不配置导航的,要开启主题的功能,继续配置 mkdocs.yml 文件,要获得各种效果,基本上只需要配置这个文件。

theme: 
  name: material
  features: 
    - navigation.tabs
image-20201204162017448

有时候你并不行把所有的目录都作为导航 tab 展示出来,你需要自己定义导航,同样可以在 mkdocs.yml 文件当中配置。 可以嵌套多级路径,但是只有顶层会显示在 tab 中,剩下的会在侧边栏展示。

nav:
  - 首页: index.md
  - 编程: 
    - python: python/index.md
    - golang: golang/index.md
image-20201204173602745

网站风格设置

官方网站有非常多风格设置的说明,可以设置外观颜色,markdown 进阶语法和 emoji 表情等等。下面是一个参考的 mkdocs.yaml 设置:

site_name: My Docs
theme: 
  name: material
  # 设置中文
  language: zh
  palette:
    # 主色调
    primary: brown
  features: 
    - navigation.tabs
nav:
  - 首页: index.md
  - 编程: 
    - python: python/index.md
    - golang: golang/index.md

markdown_extensions:
  - admonition
  - attr_list
  - codehilite:
      guess_lang: false
      linenums: false
  - toc:
      permalink: true
  - footnotes
  - meta
  - def_list
  - pymdownx.arithmatex
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.caret
  - pymdownx.critic
  - pymdownx.details
  - pymdownx.emoji:
      emoji_generator: !!python/name:pymdownx.emoji.to_png
  - pymdownx.inlinehilite
  - pymdownx.magiclink
  - pymdownx.mark
  - pymdownx.smartsymbols
  - pymdownx.superfences
  - pymdownx.tasklist
  - pymdownx.tilde

发布到 GitHub Pages

第一步:在 github 账号上创建一个库名为:<username>.github.io,把远程仓库的名称添加到本地仓库:

git remote add github https://github.com/yourname/yourname.github.io.git

第二步:生成对应的 HTML 文档,文档会被放到 gh-pages 分支下:

mkdocs gh-deploy

第三步:把本地仓库 push 到远程仓库地址,注意要把 master 分支和 gh-pages 分支都推送:

git push github --all

这里的 github 是远程仓库的名称,你也可以取其他的名字。

第四步:在 github 的项目设置里设置默认分支为 gh-pages 分支:

image-20201204193338868

访问 looker53.github.io 就可以看到项目了。

image-20201204193430258