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/

官方文档：https://squidfunk.github.io/mkdocs-material/