通过 Material for MkDocs 搭建网络安全知识库

本文最后更新于 2026年3月12日 下午

一、背景

在学习新知识时，将其记录下来既能检验学习效果，也能对整个学习过程形成闭环。常言道：好记性不如烂笔头，记录笔记的方法有很多，市面上也有各种免费或收费的工具。结合个人需求，罗列了以下几个需求：

  1. 本地可控：所有笔记数据完全保存在本地，自己掌握，随时可以迁移或备份。
  2. 互联网发布：可以轻松发布到互联网上，让更多人方便地访问和查阅。
  3. 多人协作：个人力量有限，希望能够与其他网络安全爱好者共同维护和撰写笔记。
  4. 零成本：系统的使用不产生额外费用。

二、Material for MkDocs

参考了一些高质量的知识库后，最终选择通过 Material for MkDocs 来搭建个人知识库。它与个人博客类似，采用 Markdown 转换为 HTML 的方式进行部署，操作非常简单，使用 pipx 安装即可。后期的维护与更新是核心，需要通过不断添加内容来完善整个知识库体系。

1
2
# Material for MkDocs 官网
https://squidfunk.github.io/mkdocs-material/

三、网络安全知识库搭建

3.1 Material for MkDocs 环境安装

访问 Material for MkDocs 说明文档，官方建议我们通过 Python 虚拟环境安装 pip 依赖，这里推荐两种安装方式，Windows 和 Macos 均可参考。

3.1.1 通过 pipx 安装 Material for MkDocs

通过 pipx 安装后，会得到 8 个执行程序，具体功能稍后会介绍。

1
pipx install mkdocs-material

3.1.2 创建 Python 虚拟环境安装 Material for MkDocs

使用 python 创建虚拟环境，然后使用 pip 安装。

1
2
3
4
5
6
# 创建虚拟环境
python -m venv venv/
# 使用虚拟环境
source venv/bin/activate
# 安装 mkdocs-material
pip install mkdocs-material

对于 Windows 虚拟环境，如果在 Powershell 中需要执行 source venv/bin/activate.ps1 ，cmd 则执行 source venv/bin/activate.bat 。

3.2 Material for MkDocs 参数介绍

日常使用一般只用 mkdocs 和 ghp-import 工具，接下来挑选常用功能进行介绍。

  • mkdocs：Material for MkDocs 的核心工具，可将 Markdown 文件生成静态 HTML 文件。主要负责文档构建、配置解析、服务器预览、打包发布等功能。
    • mkdocs new：创建新的 Material for MkDocs 项目。
    • mkdocs serve：启动服务，默认会开启本地 8000 端口，如果项目文档较大可通过 –dirtyreload 使得加载速度更快。
    • mkdocs build：执行构建，将 Markdown 文档转换为 HTML 文件（放置到 site 目录）。使用 –clean 每次构建前清空 site 目录。
  • ghp-import：用于将生成的静态网站快速推送到 GitHub Pages。

具体参数用例将在 GitHub 存储库创建后演示。

3.3 创建 GitHub Pages

关于本栏目可参考历史文章：

零成本搭建个人博客网站-创建 GitHub Pages 部分

3.4 发布网络安全知识库至 GitHub Pages

3.4.1 发布前初始化配置

新建一个测试项目，包含 docs 目录和 mkdocs.yml 文件，其中 docs 目录用来存放 Markdown 文本，mkdocs.yml 用来设置网站偏好信息。

1
2
# 新建项目
mkdocs new name

根据个人需求可修改网站颜色、字体、目录结构以及插件等信息。

目录示例： 可根据个人需求创建不同的知识板块，每个板块通过目录进行区分。

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
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
# 站点基础信息
site_name: F0ne's Docs              # 网站标题（显示在浏览器标签页 & 左上角）
site_description: 这是一个网络安全知识库。  # 网站描述（SEO 用）
site_url: https://f0nesec.github.io/f0nesec-docs/       # 站点正式访问地址（GitHub Pages 必填）

# GitHub 仓库相关（右上角图标）
repo_name: f0nesec/f0nesec-docs   # 图标旁显示的文字
repo_url: https://github.com/f0nesec/f0nesec-docs   # 仓库地址（右上角跳转）
edit_uri: blob/main/docs/ # 编辑代码

# 页脚版权信息
# copyright: Copyright © 2026 Martin Donath

# 额外配置
extra:
  generator: true   # 关闭、开启页脚的 “Made with Material for MkDocs”

# Markdown 功能扩展
markdown_extensions:

  # 目录 / 锚点
  - toc:
      permalink: true # 每个标题右侧生成一个 ¶ 图标

  # 提示框
  - admonition  # 启用 !!! note / warning / tip / danger 等提示块

  - pymdownx.details  # 允许提示框折叠（??? note）

  # 代码块增强
  - pymdownx.superfences  # 允许：提示框里嵌套代码，Mermaid / 多语言代码块

  - pymdownx.highlight:
      linenums: true            # 显示代码行号（核心）
      anchor_linenums: true     # 行号可点击（生成锚点）
      line_spans: __span        # Material 推荐配置（用于高亮/复制）
      pygments_lang_class: true # 给代码块加 language-xxx 类名
      auto_title: true          # 自动显示代码框类型，不定义需要通过 tilte=""指定

  - pymdownx.inlinehilite # 支持行内代码高亮：`==highlight==`

  - pymdownx.keys # 支持快捷键样式：++ctrl+alt+del++

  - pymdownx.snippets # 支持从外部文件插入代码，例如：--8<-- "code/example.py"

# 主题配置（Material）
theme:
  name: material          # 使用 Material for MkDocs
  language: zh            # 界面语言为中文
  icon:
    repo: fontawesome/brands/git-alt # 使用 FontAwesome 的 GitHub 图标
  # 主题功能
  features:
    - content.code.copy     # 代码块右上角「复制按钮」
    - content.code.select   # 代码块支持鼠标拖拽选择
    - navigation.top        # 滚动后显示返回顶部按钮
    - search.suggest        # 搜索联想
    - search.highlight      # 搜索结果高亮
    - search.share          # 搜索结果可分享链接
    - content.action.edit   # 开启查看源码
    - content.action.view   # 开启编辑源码操作

  # 颜色方案
  palette:
    # 默认深色模式
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: black       # 顶部导航栏主色
      accent: deep orange   # 链接 / 按钮 / 高亮色
      toggle:
        icon: material/toggle-switch-off-outline
        name: 切换浅色模式

    # 可切换的浅色模式
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: indigo
      accent: deep orange
      toggle:
        icon: material/toggle-switch
        name: 切换深色模式

    # 自动切换，根据系统主题自动切换
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/link
        name: 自动

  # 图标
  favicon: assets/title.png   # 浏览器标签页小图标
  logo: assets/logo.png       # 左上角站点 Logo

# 配置插件
plugins:
  # 显示更新创建日期
  - git-revision-date-localized:
      fallback_to_build_date: true  # 设置文档修改日期
      # enable_creation_date: true  # 设置文档创建日志
  # 显示作者的头像
  - git-committers:
      repository: f0nesec/f0nesec-docs
      branch: main
  # 采用压缩和转换技术优化网站
  - optimize

# 社交链接
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/f0nesec
      name: Github
    - icon: fontawesome/brands/discord
      link: https://discord.com/invite/MWKGN3AqG
      name: Discord

# 配置目录结构
nav:
  - 首页: index.md
  - Web 应用程序安全:
      - 概述: Web-Application-Security/index.md
  - 活动目录安全（域控）:
      - 概述: Active-Directory-Security/index.md
  - 移动应用程序安全:
      - 概述: Mobile-Application-Security/index.md
  - 本地权限提升:
      - 概述: Local-Privilege-Escalation/index.md
      - Windows 本地权限提升:
          - 概述: Local-Privilege-Escalation/Windows/index.md
      - Linux 本地权限提升:
          - 概述: Local-Privilege-Escalation/Linux/index.md
  - 横向移动:
    - 概述: Lateral-Movement/index.md
  - 凭证攻击:
    - 概述: Credential-Attacks/index.md
  - 代码审计:
      - 概述: Code-Audit/index.md
  - 检测与规避技术:
      - 概述: Detection-Evasion/index.md
  - 考试与认证专题:
      - 概述: Certifications/index.md
      - OSCP 认证:
        - Certifications/OSCP/index.md
      - OSWE 认证:
        - Certifications/OSWE/index.md
      - OSEP 认证:
        - Certifications/OSEP/index.md
      - OSED 认证:
        - Certifications/OSED/index.md

如若使用以上配置文件需修改一些提示信息，比如：网站 title、图标、GitHub 链接等，配置文件使用的扩展插件也需要单独安装，更多配置可查看官方文档介绍。

Python 插件安装：

1
2
3
4
5
6
7
8
9
10
11
# 若 Material for MkDocs 通过 pipx 安装需使用 pipx 安装插件
# 文档日期插件
pipx inject mkdocs-material mkdocs-git-revision-date-localized-plugin
# 展示 GitHub 作者头像
pipx inject mkdocs-material mkdocs-git-committers-plugin-2

# 通过 python 虚拟环境安装 Material for MkDocs 的可直接使用 pip 安装插件
# 文档日期插件
pip inject mkdocs-material mkdocs-git-revision-date-localized-plugin
# 展示 GitHub 作者头像
pip inject mkdocs-material mkdocs-git-committers-plugin-2

压缩插件安装（不启动图片压缩不需要配置）：

1
2
3
4
5
# Macos
brew install pngquant

# Windows
下载exe安装

目录结构和配置文件部署完成后可在本地启动服务，检查无误后再部署至 GitHub。

1
2
# 启动服务
mkdocs serve

将代码推送至 GitHub 共分为两步，首先是项目的源码推送，其次是构建的 HTML 源码推送。当然也可以只推送 HTML 源码，将项目源码推送至 GitHub 是为了协同维护知识库。

通过 Git 部署前需要进行一些初始化配置：

1
2
3
4
5
6
7
# 初始化git配置
git init
# 设置推送的GitHub仓库，注意：需要在GitHub配置好公钥
git remote add origin git@github.com:f0nesec/f0nesec-docs
# 设置邮箱、用户名
git config --global user.email "xx@xx.com"
git config --global user.name "f0nesec"

定义 .gitignore 文件，避免敏感信息泄漏：

1
2
3
4
5
6
7
.DS_Store
**/.DS_Store
site/
.cache/
__pycache__/
*.log
Git.txt

注意根据个人需求，将不想上传的文件和目录写入 .gitignore 文件。

3.4.2 推送项目源码

推送项目源码至仓库 main 分支：

1
2
3
git add .
git commit -m "update by F0ne"
git push origin main

确认 GitHub 存储库 main 分支代码已经上线。

3.4.3 推送 HTML 源码

1
2
mkdocs build --clean
ghp-import -n -p -f site

推送完成需要在 GitHub 存储库 Settings-Pages 选择发布 gh-pages 分支。

网络安全知识库链接地址：

1
https://f0nesec.github.io/f0nesec-docs

所有推送过程均在项目根目录进行。

四、补充

目前，网络安全知识库的整体体系已经初步搭建完成，主要涵盖：Web 应用程序安全、Active Directory 安全（域控）、移动应用程序安全、本地权限提升、横向移动、凭证攻击、代码审计、检测与规避技术，以及考试与认证专题。未来会根据自己的学习情况逐步完善各个板块内容，相信会是一个任重而道远的过程。

最后，欢迎广大安全爱好者加入，共同打造一个全面的中文网络安全知识库。

Thanks

如果我的文章对您有帮助或您希望与我更多交流，欢迎点击「关于我」，通过页面中的微信公众号、邮箱或 Discord 与我联系；若您发现文章中存在任何错误或不足之处，也非常欢迎通过以上方式指出，在此一并致以衷心的感谢。 😊🫡

最后，祝您生活愉快！🌞✨

知识库建设
#GitHub Pages #Material for MkDocs
通过 Material for MkDocs 搭建网络安全知识库
https://www.f0nesec.top/2026/01/20/knowledge-base-construction/
作者
F0ne
发布于
2026年1月20日
许可协议