褪色的抽象

Kaffa's blog

用 MkDocs 写文档

感叹

编程语言的哲学通常会传导到产出物中,对比 MkDocs 和 Hugo,前者从安装到使用都简单直观多了。

为什么是 MkDocs ?

如其名,一个编写文档的 Python 包,使用的 MarkDown 语法,上篇提到本年正转向 MarkDown 格式输出,据学习规律,应在多场景中重复创造练习的环境。

给自己的 MkDocs 使用说明

首先是安装,因为是 Python 包,所以在当下使用目前官方默认的包管理工具 pip install 即可。

其次是使用,在开箱即用会打开首页,包含几个常用命令和目录结构。

命令

  • mkdocs new [目录名] - 创建项目
  • mkdocs serve - 开始实时刷新的文档服务器监听
  • mkdocs build - 生成文档
  • mkdocs -h - 打印帮助并退出

目录结构

mkdocs.yml    # 配置文件
docs/
    index.md  # 文档首页
    ...       # 其它页面,图片和其它文件

最后,MkDocs 主题并不是很多,使用默认主题或喜欢的即可,Material for MkDocs 还不错

思路

为了寻找一个写文档的包,可以在 Github 搜索;如果对软件的编程语言有要求,可以加上语言作为关键字,比如:Python Documentation 这里就会得到开源项目的列表,按照排名翻一下前几页会找到很多知名的项目。

另外,世界排名后几名的开源站,也会有很多的经典项目。

如果是对静态站点生成器这个主题内容感兴趣,可以去 Site Generators 看看,那里有一个排名。

搜索关键字

Python, MkDocs, MkDocs Theme

感谢阅读。