modified	Thursday 1 May 2025

Edited: Thursday 1 May 2025

Friday, October 1, 2021 at 11:20
+

笔记文档一把梭

100gle

少数派

MkDocs 快速上手指南

引言

在无纸化信息处理的流程中 , 信息输入、信息整理阶段的工具选择已经
很多了 , 雨后春笋般不断浮现的笔记工具让人眼花缭乱。但到了信息输
出和展示的环节一一例如发表自己的读书心得、思考或是学习笔记 , 或
i ti :

一方面 , 如果选择语雀、Notion 这样的第三方云端文档平台来存放 ,
定制空间就很有限 , 且数据始终是寄人簪下。另一方面 , 如果选择
WordPress 这类 CMS 或近年流行的 Jekyll、 Hugo 或是 Hexo 等「静态
0 , 随之而来的技术门榛和复杂操作又容易打消人的创作和
刀字烈促。

以我个人为例 , 我想通过搭建简单的静态网站来很好地展示我在学习编
程过程中的所作的笔记、对问题的看法等 , 将它们作为一个 Cookbook
或系统化的参老文档来使用 , 同时也兼具美观和可读性。对此 , . 上述主
流框架都有些 T 条鸡用牛刀」的感觉 , 那么 , 有没有更好的方式限 ?

我遇见的答案是 MKDocs。
什么是 MkDocs?

MkDocs (Markdown Documents) 是一个快速、简单的静态网站生成
器 , 用于将 Markdown 文档组织起来构建成有层次、美观的文档站点。
MkDocs (《Markdown Documents) 是一个快速、简单的静态网站生成
器 , 用于将 Markdown 文档组织起来构建成有层次、美观的文档站点。

东 o e * 国

< 口 8 moimmmriiceoc 英文国日明真真口交自国一

MKkDocs

Pageidocomeionwstdom

octeton oementoncecee
caveninetdows ondcofooed esinge conhyuaton e Sutiyesirg etedcey d bendeck e Code
C

ec anglecnddowneghtgogeeuasotc cgcoesenesesedlonndctoiergm

Greatthemes available Easy tocustomize
Isosncrolooogiotngiercanisseleninooe erponciooeonesoniosengimewenowennn
Doosbeeeneboinierwe ntcecsandnsonedcc caseranoyuriiersanderieaingsonepoare
ectorogiemuepuyeresineeonteocs Meaty s woenesone ha
Ienarmiinoee rmiaicrom < Corn

Preview yoursite as youwork Hostanywhere
evarndecconsnolonnyooloremeee Maoocsbaoconeeiy utc imcstesetyesconhe
conenutonssyounenigi nernosand cupeges nan St nonrnieedeyouciecae

mhednyoutbonecmieneeyoucoeyoecenge

MkKDocs 基于 Python 编写 , 也贯彻了 Python 里「简洁胜于复杂」的理
念 , 与其他常见的静态网站生成器相比 , 无需繁琐的环境配置 ( 如
Jekyll 涉及的 Bundler、Gems 等 ) , 所有配置都用足有简单的一个配
置文件管理 , 并且当中配置项的内容也仅有一页文档。

MKDocs 见名知意就是为 Markdown 而生 , 根据 Markdown 格式将内容
渲染成美观的文档 , 并通过目录层级关系对应文档的树状结构 , 使得当
中所有的文档组织分明且层次递进。

E illUUicduirihriuttitniidii 5 时 on

Jekyll 涉及的 Bundler、Gems 等 ) , 所有配置都用只有简单的一个配
置文件管理 , 并且当中配置项的内容也仅有一页文档。

MKDocs 见名知意就是为 Markdown 而生 , 根据 Markdown 格式将内容
渲染成美观的文档 , 水级关系对应文档的树状结构 , 使得当
中所有的文档组织分阮且层次递

鱼目 @ 日 wy 0ocs x 十

人〇 @ 127.0.0.1:8000 骑亢 “ 囚 “ 图。申

早 _& 明 _ 跌叶失白屋

My Docs Q Search

Welcome to MkDocs | Welcome t MKkDocs

Commands Forfull documentation visit mkdocsorg.

Project layout | c d
0mmanQds

nkdocs new [dir-nane] - Create a new project
nkdocs serve - Start the live-reloading docs server
nkdocs buitd - Build the documentation site.

“ nkdocs -h - Print help message and exit

Project layout

mkdocsynt 。芒 The configoration 仁 le。
docs/

dndex.md 芒 The docunentation homepage,
C 芒 ther parkdown pages, Lnages ang other 秀 les.

Documentation builtwith MKDocs

1 月 sd 一 i [ T rr 林 C 一东一人口日一厂干一 a 5 人 /
T
为 Markdown 增加列表语法等 ; 我们也可以对 MkKDocs 构建的站点的
布局样式进行二次定制和编排 , 使得整个站点更加美观。

MkDocs 的上述优点 , 让它被很多知名开源项目选中 , 用于搭建和项目
相关的文档扇站。比如 Eython 里知名的 Web 团里的 djanggo-rest-
framework、FastAPl 以及基于 CC 编写的云团关位理服劳碧 raefik 等
项目的官方文档站点 , 都是通过 MKDocs 进行指建。

当然 ,MkDocs 并不仅仅是开发者的玩物。由于文档的本质就是一组结
构化、体系化的说明文本 , 任何具有这种特征的内容一一例如就特定话
所做的笔记、Wiki 等一 - 只要是使用了 Markdown 格式记录 , 那么用
MkDocs 来搭建一个自用的 Cookbook 或参考手册也完全不在话下。

鲜园 @ O aposcux x |
< 〇 @ tmoonsooopyionpresy 公四国日园 @ 目路口主申
串 Pytest @.,Q
简单用例
Fesleaek
Pasheaek 信用 sssert 关铁朱逼行新言 , 知梁目失货可以窑接揽出应的佳
Pyon 、
Dgnge 5 dmport pyiest E
Pask > sr f 标 2 Inaf
Aiahtp return 3 李 S ponmetze
Apchedoer def test 河 Bl
Pet go f0 Palue wos dd should be ever 颅 d 用 8 skp 命 skpt
E s
Ja 》 spf
com , 标记 (mark) R useoaoee
Datibase 》 2
o 》 mover 是 pytest 特玲的一科标识 , 必以裆洁的式木裂余箭骗制的团数 , 包招洁定澈讨参 SE 亨 X
数、是西跳汝答、我 f 可侦 pytest –aerkers 朱真真所有记。 ngSA
西 R: baune

参数测访 : parametrize sope f

paranetrize 标 2 史用于挂宏筠刻函数的去经测论夕数它积 fixture 不网的地市在于它古

能作用于当莲松的国政或踹征 3 明
dmport pytest 内页

sntp 积 adom
outpat“.[00.(2.22).(8.35).044010

Spytestumark parametri 0 MX
notpub

def testmutiplicatio
sssert n

M 达
E
E se
如根要狭得孙个去勒的所有绍合 , 可 b 棣敌多个 parsmetrize 裂 : 口

MKDocs 春个不错的选择。
注 : 尼管 MkDocs 没有提供汉化翻译 , 但它的文档内容足够简洁

了 , 所以即使读者对自己的英语水平东太有信心 , 也可以在翻 1
和示例项目的帮助下 , 快速上手并构建一个站点。

伍速上手

下面 , 我们来尝试从无到有用 MkKDocs 制作一个网站 , 顺便对它的轻
量快捷建立一个直观认识。

首先 , 请确保自己安装了 Python3, 然后通过命令 pip instal1
mkdocs 安装 MkKDocs。然后 , 按照下列步骤新建站点

使用 mkdocs new 新建站点项目 ,
比如我这里叫 mysite, 则是 mkdocs new mysite ;
切换到 mysite 目录下 , 并使用 mkdocs serve 在本地运行。

第三步 …… 没有第三步了。现在打开浏览器 , 输入 localhost:8000,
就能预览到 MkDocs 帮我们搭建好的文档站点了。

osttoos 2 RPR ER 工 XR M SD ie

对于这种情况 , 直接在原有目录下新建一个 aocs 文件夹并包含一个名
为 indaex.md 的 Markdown 文件 ; 同时在原有目录下再新建一个名为
mkdocs.ynml 的文件并填写基本信息之后 , 就能直接通过 mkdocs serve
看到效果了。例如 :

my-exist-projct

[ 一 docs

厂 index.md

厂 notes

| | mkaocs.mad
| L 一 python.md

L 一 sspai

一一 mkdocs .Yml

i MKkDocs 搭建的文档站点 , 都有着和上述示例类似的目录

。 docs 文件夹就是用于存放我们所有的 Markdown 格式的文档内
容 , 当然我们也可根据自己的需要进一步用文件夹归类划分 , 这
也是 MkDocs 运行时默认的根路径。我们也可以后续手动指定修
改成其他目录。

。弥 c .yml 该文件主要用于 MkDocs 的定制化配置的设置与管

。 docs/index.mad 该文档内容是必须要有的 , 它是整个 MkDocs 构
建的首页入口

因为 MKDocs 只会对 Markdown 文件进行处理 , 因此我们除了需要将
自己电子化的记录或者笔记放到 docs 这一目录之外 , 还需要确保这些
女档女位的扩展书为 _ 的 Markrnwn 栓汀 _

C d 一 ld

文档文件的扩展名为 .ma 的 Markdown 格式。

确保结构、格式没有问题后 , 我们就可以开始编写相关的配置文件了 ,
国免吴有编写了配置文件才能让 MkDocs 更好地符合我们的需要去构
页

Anvo

插曲 : YAML 配置文件格式速成

稍等 ! 虽然我们准备好了相关 Markdown 的文档内容 , 但想要 MKDocs
炎闪 H 伟那就是编写关于 MkDocs 的配置文

和前面提到的其他几个框架一样 ,MkKDocs 也存在许多可选配霁 , 需要
通过 mkaocs .yml 这一个 YAAML 文件来进行设置和管理。因此我们需要
简单了解一下 YAML 以及如何编写 YAAML 文件。

YAML 是 YAML Aint Markup Language 的递归缩略语 , 也是一种人类
可读 (human-readable) 的数据序列化语言 , 其文件扩展名为 .yml 或
月 1 。常被用作和 JSON 格式文件一样编写配置或存储

河洁皇胡师李根长连人十孙页 ( 善心疯技 e 仪一丨侃页尼眸一
其支持的语法特性有多么丰富。不过 , 虽然文档长度很唱人 , 但「
怎挂 1 罗技连筹 7 贺升 01 时许宏动春医沥佳诊根绍形性用男汀
20%f 的语法并不常用 , 需要我们额外查阅文档。不仅如此 , 由扎
MkDocs 本身配置项就不多 , 因此我们在编写 rtkaocs.yml 旷 ,

到的 YAML 语法可能不到 10%。

这样一来 , 我们只需要谨记以下三个核心元素的用法 , 就能应付大多数
YAML 配置需求 , 包括本文的主角 MkDocs:

键值对 (Key-Value Pair)
缩进 (indent)

“ El “ 巴仪三一 Ab 工毛必 54
w RD 相 T 小 , 巳 J 尸个一 y 二 / 李 e

键值对 (Key-Value Pair)
2 缩进 (indent)
. 同一层级下不能有重名键

键值对

eu 这其实理解
为 1 标记与内容的对应形式」即可。

键值对在 YAML 中的形式如下 :

name: 100g1e

其中的标记 ( 键 ) 就是上面的 name, 在现实生活中可以表现为我们很
多属性的代称 , 伟认职位等等 ; 而内容 ( 值 ) 就是这些代
称下的具体详情 , 比少数派鸽子等等。这在 YAML 中通过
一个 : 英文冒号将二婉明招洁这等价于编程语言里的 = 等于号。
缩进

YAML 用空格缩进来表示层级关系 , 这区别于另一种流行配置格式
JSON 使用的花括号 {}, 可能是受到了 Python 的影响。

family :
father :
name : foo
age: 100
Child :

name : bDaZ
需要注意的是 , 空格 (ASCI 码值为 32) 有的时候会和 Tab 键产生的
制表符 (ASCI 码值为 9) 混在一起 , 二者单从外观上来看无法分辨 ,
因此为避免 YAAML 解析错误 , 我们在编写时要遮循 YAML 官方缩进的
要求使用两个半角空格。

同一层级下不能有同名键

了解键值对和缩进值后 , 我们还需要注意的一点就是 YAML 不允许在同
一层级下出现相同的键 , 例如 :

father :
name : foo

age: 100

family :
father :

name : foo

age: 3

father : foo
father: foo

在这个例子中 father 和两个 family/father 键 ( 行文方便起见 , 我这
里会以文件路径的形式表现层级关系 ) 虽然同名 , 但因为它们并不在一
个层级中 , 因此并不会产生冲突。

但是在 family 中 , 第一个 family/father 会和第三个 family/father
产生冲突 , 因为它们同级且同名。

这就好比在同一个班级里有两个同名的张三 , 同学们如果只是看名字肯
定都没办法分辨得出提到的是哪个张三 , 更别说程序和计算机了。

在 mkdocsyml 中编写配置

了解了 YAML 的简单用法之后 , 我们就可以编写 mkaocs .yml 文件了。
在编写的过程中我们会碰到字符串和列表的表达语法 , 但我并不打算在
这里再继续展开 , 因为它们十分简单 , 一看便能知道。

关于 MKDocs 支持的所有配置你都能在官方文档中找到 , 但当中的配
置我们只需要填写关键的几个即可。

添加站点信息

最开始在 mkdocs.yml 文件中填写的主要还是关于站点相关的信息。其
中我们可以填写的有那么几个 :

Site_name : 站点名称
site_ur1: 站点 URL 链接
Site_author : 站点作者
site_description : 站点描述

F 人 h r 1 连人门口口
中我们可以填写的有那么几个 :

s site_name: 站点名称

s site_url1: 站点 URL 链接

s site_author: 站点作者

s site_description: 站点描述
s copyright: 版权信息

s repo_url1: 站点仓库 URL

其中 , 只有两个必须要填写的配置项就是 site_name 站点名称和
site_ur1l 站点 URL 链接。例如 :

site_name: “My Notes“

site_url1: “http: //:/“

但如果我们使用的是 ,mkaocs serve 来本地运行 , 那么无需填写
site_url, 因为 MkDocs 会自动将其挂在本地的

http://127.0.0.1:8000/。

除此之外的选项都是选填 , 如果填写了则 MkDocs 会将其作为元数据
或元素渲染最后的 HTML 中。

添加文档路径

既然我们想要搭建的是一个文档站点 , 那么文档内容才是关键 , 除了对
内容进行必要的排版校对之外 , 如何组织文档或是让文档以清晰有层次
的结构展示也是必不可少的。

MKDocs 提供工让使用者能够自由安排文档层级结构或目录编排的设
置 , 这将决定最后文档在站点中的编排效果如何。这里主要是通过 nav
项来进行配置 :

DaV :
既然我们想要搭建的是一个文档站点 , 那么文档内容才是关键 , 除了对
内容进行必要的排版校对之外 , 如何组织文档或是让文档仪清晰有层次
的结构展示也是必不可少的。

MKDocs 提供工让使用者能够自由安排文档层级结构或目录编排的设
置 , 这将决定最后文档在站点中的编排效果如何。这里主要是通过 nav
项李进行配置 :

nav:

“index .md「
user-guide :
_quickstart: “user-guide/quickstart .md “
usage: “hser-guide/how-to-use-MKDocs .md 「
“about .md 「
“1icense.md「

在该设置项中 , 使用了 YAML 所支持的列表语法 , 这和 Markdown 的
无序列表语法是完全一致。默认情况下如果不指定键名 ,MKkDocs 会自
动根据列举的 Markdown 文件名字符串来确定最终该页面的名称如何 ;
如果我们手动指定了键名 , TE 比如这里的

user-guide/usage 这一部

需要注意的是 , 前面对于水 MkDocs
默认会将项目目录下的 aocs 目录作为默认的根路径 , 所以在 nav 设置
小技芸沥暨居是雯心林目余吊命那么就是只需要填写相对路
代。

这也是为什么在上述例子中的 user-guide 这一部分下的文档路径都不
需要写成 docs/user-guide/XXXX.md 的原因。
中我们如果指定的是该目录下的其他内容 , 那么就是只需要填写相对路
代。

这也是为什么在上述例子中的 user-guide 这一部分下的文档路径都不
需要写成 docs/user-guide/XXXX.md 的原因。

同时 , 最终 MkDocs 也会根据 nav 配置的层级关系将内容的层级关系
或包含关系一同渲染。

当然 , 如果你不想使用 MKDocs 的默认目录 , 那么你也可以通过修改
adocs_dqir 选项来指定对应的文件夹名称。但通常情况我们都不需要进
行修改就已经能满足我们的基本需要了。

用扩展和主题武装 MkDocs

基本上我们只需要将站点信息和文档路径在 mkaocs .yml 文件中填写好
就已经可以运行 MkDocs 了。不过 MkDocs 为使用者预留了可扩展的
配置 , 方便使用者去添加其他开发者所开发的主题、扩展等功能。

Markdown 扩展

MkDocs 使用 Python-Markdown 库 (Markdown 规范的 Python 实现 )
来渲染 Markdownh 内容 , 因此 MkDocs 中对于 Markdown 内容渲染的
扩展也是来自于此。我们可以在 Python-Markdown 的官方文档中浏
览到目前所支持的「Markdown 扩展有哪些。

1 一 Markdown 内容标题的固定标识符、脚注以及表
markdown_extensions :

toC :

permalink: True
MkDocs 使用 Python-Markdown 库 (Markdown 规范的 Python 实现 )
来渲染 Markdownh 内容 , 因此 MkDocs 中对于 Markdown 内容渲染的
扩展也是来自于此。我们可以在 Python-Markdown 的官方文档中浏
览到目前所支持的「Markdown 扩展有哪些。

1 一 Markdown 内容标题的固定标识符、脚注以及表

markdown_extensions :

toc:
permalink: True
footnotes

= 七 ableS

除此之外 ,Python-Markdown 还支持一些来自于第三方的 Markdown
扩展你能在 Python-Markdown 的 Github 仓库中的 Wiki 页面找到符
佳绫需要的扩展 , 比如支持数学公式、emoji 表情、增强 Markdown 语
/ 八如

但这些第三方扩展都还是需要通过 pip 工具 ( 安装 Python 解释器时会
自带 ) 来进行安装 , 安装之后在 mkdocs.yml 中的 markdown_extension
部分继续追加。

这里我下载了一个名为 markdown-checklist 的扩展 , 使我的
Markdown 文档内容支持清单列表的预览样式。

pip install markdown-check1is 七

安装完成后将其添加到 markdown_extension 中 , 注意 , 这里是需要安
装插件对应文档的名称来填写包含相应的 makeEgxtension 属性的模块
动姚孟了 Markqnwn 店中 rs+anain 的娄 “ 所 | 我设惧 A 了
或继承了 Markdown 库中 Extension 河所以我就填入了

ImiaIL kdown__ checklist .extensionl 这一

markdown_extensions :

toc :
permalink: True

footnotes

七 abl1eS
markdown_check1ist.extension

最后运行 MkDocs 后就可以看到其对应的效果了。

园 FlaskBack

气立 D “@ 1270.01:8000 “ 善克 @@ _ 围明智 _ 口明 , 六白屋

FlaskBack

口 | 为 Hithere

“ v taskK2
《 tasK3

王育 2 MKDocs 默认的主题已经相当简约美观

不过 , 如果你有一定的 HTML、CSS 以及 JavaScript 基础 , 对 MkDocs
默认的主题样式存在某些想要定制化的部分 , 那么你可以通过设置

extra_templateS 、 eXxta_CSS 和 extra _javascript 二三个选项来进行
局部调整。哪怕你是想从头到尾自己定制一套主题样式 , 那么 MkDocs
也能如你所愿 , 还有专门的文档来指导你如何去操作。

当然 , 更多时候我们会希望直接套用别人定制好的主题。对此 , 你同样
i MkDocs 的 Github 仓库中的 Wiki 页面中找到你心仪的主题样
工 vo

无论是自己定制还是使用第三方的主题样式 , 想要主题样式生效 , 最后
都需要通过配置文件中的 theme 项来进行配置。

比如我这里使用了目前使用度最广泛的 MkDocs 第三方主题样式
Material for MkDocs, 使得 MkDocs 能够以 Google 推行的 Material
Design 风格呈现

但因为该主题属于第三方主题样式 , 我们需要使用前面安装 MkKDocs
使用的 pip 工具进行安装 :

pip install mkdocs-material

安装完成后 , 我们只需要在 mkdocs.ymil 文件中进行配置即可 :

theme :

name : mate1al

之后我们就能得到一个 Material Design 风格的 MkDocs 站点了 , 这个
站点甚至还有自适应的暗黑模式 (Dark Mode) 。
HA e - 一 4 GeoGoeo e e

临 Apscheduler

Pasiesex

Pasesex

夙可 M 朋阜有步

djet0 有法

站点生成与部署

如果你只是临时用于离线浏览文档 , 那么使用 mkdocs serve 命令其实
足矣 ; 但如果你是打算作为个人站点或主页部暑到云服务器 , 那么你就
需要将整个文档项目编译打包 , 最后放到对应的服务器上部署。

这里 MkDocs 给我们提供了两个选项 : 一个是使用 mkdocs build 命令
将项目打包之后 , 再由个人将打包文件上传至服务器对应的目录下进行
部署 ; 另外一个就是如果你有打算使用 Github Pages 来作为展示的站
点 ( 参见 GitHub Pages 搭建教程 ) , 那么我们就只需要使用 mkdocs

gh-aeploy 这一条命令就可以帮我们完成部署任务。

人仁应人水心一 c t 门口

这里 MkDocs 给我们提供了两个选项 : 一个是使用 mkdocs build 命令
将项目打包之后 , 再由个人将打包文件上传至服务器对应的目录下进行
部署 ; 另外一个就是如果你有打算使用 Github Pages 来作为展示的站
点 ( 参见 GitHub Pages 搭建教程 ) , 那么我们就只需要使用 mkdocs
gh-aeploy 这一条命令就可以帮我们完成部署任务。

该命令的过程主要是先将编译打包好的相关资源文件 ( 如 HTML 页
面、样式、静态资源图片、用于交互的 JavaScript 等 ) 上传至对应个
人 Github 用户名的 Github Pages 仓库中 , 然后再利用 GitHub Actions

来保持站点活跃。

这样我们每次只需要在本地更新内容之后 , 通过该命令进行提交、部
署 , 就可以实现文档内容的更新。

DERELNIELNLL SILIIGL

sanewiepostoy onthe commandine

nponcm

相相 Microsoft

pooao

主白广

a +- @-

园 Microsoft

注 : 由一仪定时间 ( 大约在几分钟到十分钟不
等 ) , 因此部署完成后你需要等待一会儿才能看到 Github Pages 生
效 , 口贤妮邹环 404 错误。

士 1 五
结语

对程序员来说 , 大部分时间都花在了写文档和 Debug 上。 e
过相应工具来慢慢排查并通过少量代码去解决 , 但除了自动生成的文档
之外 , 大部分情况下都必须要人为撰写。可内容写出来是一回事 , 展示
得是口妥当又是另外一回事。

使用 MKDocs 就像 Markdown 一样 , 一定程度上能够减少使用者内容
e 而让使用者能更加专注于记录或写作的
谷 o

吊

可根

关于 MkKDocs 的更多内容本文五没有进一步展开 , 但如果你有兴趣或
有需要 , 可以到 MkDocs 的 Github Wiki 页面进一步探索 MkDocs 生

Z o

Backlinks