跳转至

Mkdocs 配置记录

环境说明

  • python -> 3.9.6+

依赖包：

包名 版本 说明
Markdown 3.9 MkDocs 的核心依赖，所有 Markdown 渲染工作都基于它
mkdocs 1.6.1 核心框架，提供命令行工具
mkdocs-awesome-pages-plugin 2.10.1 增强 MkDocs 默认的导航生成能力
mkdocs-get-deps 0.2.0 用于管理 MkDocs 插件和主题的依赖关系，确保所需的包被正确安装
mkdocs-material 9.7.1 提供一套美观、响应式、功能丰富的界面样式
mkdocs-material-extensions 1.3.1 增强主题的体验，例如更好的图片对齐、自定义属性、额外 CSS 等
pymdown-extensions 10.20 为 Markdown 增加大量实用语法，让文档更生动

使用python安装

安装最新版本

1.安装mkdocs

Bash
1
pip install mkdocs

2.安装主题（也可以安装别的主题）

Bash
1
pip install mkdocs-material

安装特定版本

需要注意

每个版本配置文件可能有些区别

vim requirements.txt

Python
1
2
3
4
5
6
7
Markdown==3.9
mkdocs==1.6.1
mkdocs-awesome-pages-plugin=2.10.1
mkdocs-get-deps==0.2.0
mkdocs-material==9.7.1
mkdocs-material-extensions==1.3.1
pymdown-extensions==10.20
Bash
1
pip install -r requirements.txt

创建项目

Bash
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 给项目起个名称mkproject
root@pts/0 # mkdocs new mkproject
INFO    -  Creating project directory: mkproject
INFO    -  Writing config file: mkproject/mkdocs.yml
INFO    -  Writing initial docs: mkproject/docs/index.md

# 目录结构如下：
root@pts/0 # tree mkproject/
mkproject/
├── docs
│   └── index.md
└── mkdocs.yml

1 directory, 2 files

启动服务，本地预览

Bash
1
2
3
# 进入到项目目录
cd mkproject/
mkdocs serve

个性化配置

这里使用上边安装的mkdocs-material主题

Bash
 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
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
# 编辑mkdocs.yml配置文件
vim mkdocs.yml

site_name: 纷扰的world
dev_addr: 0.0.0.0:8000
copyright: Copyright @ 2026-01 blog.lovev.top All Rights Reserved

plugins:
  - search  # 显示启用搜索
  - awesome-pages:  # 文档目录的排序，.pages定义
      sort_type: natural  # 自然排序，2在10之前
      order: asc  # 正序
      strict: false  # 错误时只显示警告

theme:
  name: material
  icon:
    logo: material/github
  language: zh
  # font: false  # 字体设置
  palette:
    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: white
      toggle:
        icon: material/brightness-7
        name: 切换暗色模式

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: black
      toggle:
        icon: material/brightness-4
        name: 切换亮色模式
  features:
    - navigation.instant # 导航即时加载
    - navigation.tracking # 锚点 URL会自动更新为目录中突出显示的活动锚点
    - navigation.tabs   # 导航标签
    # - navigation.sections # 左边栏分组展开
    # - navigation.expand # 默认左边栏全部展开
    - navigation.path  # 文档顶部显示路径
    - navigation.top    # 返回顶部按钮
    - navigation.footer # 页脚下一页
    - toc.follow  # 活动锚点始终可见
    - search.highlight  # 搜索高亮
    - content.code.copy   # 代码复制

extra:
  generator: false

markdown_extensions:
  - abbr # 缩写
  - admonition # 注解
  - attr_list  # 属性列表
  - footnotes  # 脚注
  - def_list  # 定义列表
  # - tables  # 数据列表，默认开着
  # - md_in_html  # 支持html代码块
  # - pymdownx.arithmatex # 用于TeX数学公式的展示
  - pymdownx.caret  # 上标
  - pymdownx.tilde  # 下标
  - pymdownx.mark   # 等号高亮
  - pymdownx.critic # 支持块背景高亮
  - pymdownx.details # 详解
  # - pymdownx.emoji # emoji 
  - pymdownx.highlight:   # 代码高亮
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite  # 内联高亮显示代码
  - pymdownx.smartsymbols # 特殊符号
  - pymdownx.snippets # 片段
  - pymdownx.superfences  # 超级围栏，允许任意嵌套
  - pymdownx.betterem  # 斜体,粗体,粗斜体
  - pymdownx.tasklist: # 任务列表
      custom_checkbox: true
  - pymdownx.magiclink # 自动超链接
  - codehilite:
      guess_lang: false
      linenums: false
  - toc:
      permalink: true
  - pymdownx.tabbed:  # tab选项卡
      alternate_style: true
  - pymdownx.blocks.admonition # 替换admonition
  - pymdownx.blocks.caption # 添加字幕的功能
  - pymdownx.blocks.definition
  - pymdownx.blocks.details
  - pymdownx.blocks.html
  - pymdownx.blocks.tab

# nav:
#  - 首页：
#    - 介绍：日常运维/mkdocs使用.md
#  - 日常运维：
#  - 系列文档：
#  - 关于：