使用 MkDocs 快速搭建文档系统


MkDocs 是快速,简单和华丽的静态网站生成器,可以构建项目文档。文档源文件在 Markdown 编写,使用单个 YAML 配置文件配置。 MkDocs 基于 python,但只需编写 Markdown 就可构建最简单的文档页面

安装

使用 pip 安装 MkDocs

1
pip install mkdocs-material

创建项目

使用如下指令创建一个名为 name 的项目

1
mkdocs new name

生成的项目结构

1
2
3
4
name
├─ docs/
│ └─ index.md
└─ mkdocs.yml

配置项目属性

找到项目中的mkdocs.yml,根据官方文档进行合适的配置 这是我使用的配置,可供参考

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
site_name: XXX 使用文档
theme:
name: material
language: zh
# 网站左上角显示的logo
logo: images/logo.jpg
# 网站图标
favicon: images/favicon.ico
features:
- navigation.instant
- navigation.tabs
- navigation.sections
- navigation.expand
- navigation.top
palette:
- media: "(prefers-color-scheme: light)"
scheme: default
primary: indigo
accent: red
toggle:
icon: material/toggle-switch-off-outline
name: Switch to dark mode
# 深色模式
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: deep orange
accent: red
toggle:
icon: material/toggle-switch
name: Switch to light mode
extra_css:
- stylesheets/extra.css
markdown_extensions:
- attr_list
copyright: Copyright © 2021 XXX
extra:
# 右下角的超链接
social:
- icon: fontawesome/brands/github
link: #
name: github

编写 Markdown 并构建网页

编写前可以创建一个实时预览的服务器

1
mkdocs serve


docs/中创建的md文件将会实时同步到预览服务器 完成编辑后使用

1
mkdocs build

即可生成静态网页文件,可以部署到github pages或者你的个人服务器上

例:https://docs.bluesdawn.top/BDbot/
官方文档:https://squidfunk.github.io/mkdocs-material/