MkDocs + GitHub Pages 笔记本构建入门

说明
本文核心内容在笔者的笔记本网站原文中亦有记载，此页面为整理重制版。

前言#

笔者在大一暑假（2023 年）接触到诸多学长的网页笔记本，逐渐对这种结构化、共享化记录自己的知识体系的方式产生兴趣。经过一段时间的探索与实践，笔者决定使用 MkDocs 与 GitHub Pages 这一工具来搭建自己的网页笔记本。一番折腾过后该网站于 2025 年春逐渐成形，本文即将网站的完整创建流程进行整理与分享。

与网上其他大部分教程不同的是，本文不会花非常大的篇幅来描述 MkDocs 站点的详细配置，而是侧重于小白在搭建 MkDocs 站点时可能会遇到的问题和解决方法。

由于本站并不是所有人眼中的最佳形态（包括笔者自己），所以请各位有更好的建议请不吝赐教，笔者将不胜感激。

网页成果展示#

homepage list note friends

总体构建思路#

为了搭建我们的笔记本，我们需要哪些东西？

把我们的文档从 Markdown 格式转为网页格式的工具，让网站能被自己看见；
把这个静态网站部署到互联网上的工具，让网站能被别人看见。

网站生成#

对于第一个工具，笔者的选择是 MkDocs + Material for MkDocs。MkDocs 是一个基于 Python 的静态网站生成器，详情见 MkDocs 官网。

实际上，生成静态网站的工具远不止 MkDocs 一家，还有诸如 mdBook、Hugo 等等，本文以 MkDocs 为例，对整套流程熟悉之后，再尝试其他工具也会更加容易。

至于为什么选择 MkDocs？ 笔者认为作为一个笔记本来说，最重要的是排版简洁和清晰，并且易于维护。在实操之后，读者会发现 MkDocs 的上手非常容易，而且对于新文档的添加与网站的维护非常简单和便捷。同时笔者认为笔记本不应该具有太多的花哨的效果，而是应该更加注重内容本身。

你也许会发现 MkDocs 官网的样式似乎有些简陋，与本站不同。因为本站还用了最著名的 MkDocs 主题 Material for MkDocs，详情见 Material for MkDocs 官网。本教程的大多数内容也是参考这个主题的文档，请读者务必以 Material for MkDocs 的文档为准。

网站部署#

对于第二个工具，我们需要一个“服务器”，来将我们的网站内容展示给用户。笔者选择了使用 GitHub 来托管网站源文件，并使用 GitHub Pages 来部署网站。

GitHub 的作用不必多说，作为全球最大的代码托管平台，它提供了免费的静态网站托管服务 GitHub Pages。详情见 GitHub Pages 官网。

实际上，GitHub Pages 并不是唯一的选择，还有诸如 GitLab Pages、Vercel、Netlify 等等，这些服务都提供了免费的静态网站托管服务，甚至这些服务在速度上可能还会更快。本教程选择 GitHub Pages 的原因是足够简单，因为网站代码本身就托管在 GitHub 上，所以直接使用 GitHub Pages 部署更加方便。

这是一个非常简单且零成本的部署方式，只需要一个 GitHub 账号，就可以免费部署一个甚至多个静态网站，还可以绑定自己的域名（如本站）。

准备工作#

基础知识#

你需要有：

一定的 Markdown 语法基础；
一定的命令行操作能力；
一定的 Git 使用经验；
针对想 DIY 主题的用户，需要一些 HTML、CSS、JavaScript 基础知识；

笔者正在使用 MacBook，所以相关操作除非特殊声明，否则都是基于 macOS 系统的。Linux/Windows 用户请自行替换相应命令（实际上主要是命令行操作的小差异，其他内容基本一致）。

注意
对于本教程每一步涉及到的操作和命令，请读者先理解为什么这样做再执行，不要盲目复制粘贴。

后续中“本站”一般指的是笔者的 MkDocs 网站。

Git 环境#

macOS 和 Linux 应该是自带的，Windows 用户可以从 Git 官网下载安装包安装，网上有很多教程，这里不再赘述。

Windows 用户安装 Git 时，可以选择安装 Git Bash，安装好之后可以使用 Git Bash 来执行命令，这里面可以用一些常用的 Linux 命令，比如 ls、cd 等等（当然现在的 Terminal 也支持了）。

安装好后，记得设置好用户名和邮箱：

1
git config --global user.name "Your Name"
2
git config --global user.email "xxxxxx@xxxxx.com"

Python 环境#

对于 Linux/macOS 用户，可以选择自己习惯的包管理器安装 Python，如：

1
brew install python

对于 Windows 用户，可以直接从 Python 官网下载安装包，安装时务必勾选“Add Python to PATH”。相关的教程在网上非常多，自行搜索即可，最终效果是在终端中输入 python --version 和 pip --version 后能够看到版本号即可。

Python 环境管理

更推荐的做法是采用 Python 环境管理工具进行单独的 Python 环境配置，例如笔者使用的就是 Miniconda，这样可以避免不同项目之间的依赖冲突。

MkDocs 环境#

直接安装 Material for MkDocs 即可，它会自动安装 MkDocs：

1
pip install mkdocs-material

除了 pip 之外，还可以通过 docker 和 git 安装，详情见 Material for MkDocs 官网，这里不再赘述。

最终安装的效果是在终端中输入 mkdocs --version 后能够看到版本号即可。

本地开发#

初始化并运行 MkDocs 项目#

终端进入到你想要存放 MkDocs 项目的目录，然后执行：

1
mkdocs new site

其中 site 是项目的名称，可以自定义，这个命令会在当前目录下创建一个名为 site 的文件夹。进入 site 文件夹，里面包含 MkDocs 项目的基本结构：

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

docs 文件夹是存放 Markdown 文件的地方，mkdocs.yml 是 MkDocs 的配置文件，这两个文件是 MkDocs 项目的基础。

在此目录下输入：

1
mkdocs serve

你可以看到命令行输出：

1
❯ mkdocs serve
2
INFO    -  Building documentation...
3
INFO    -  Cleaning site directory
4
INFO    -  Documentation built in 0.03 seconds
5
INFO    -  [11:09:37] Watching paths for changes: 'docs', 'mkdocs.yml'
6
INFO    -  [11:09:37] Serving on http://127.0.0.1:8000/

这时前往链接 http://127.0.0.1:8000/，你会看到一个简单的页面，这就是 MkDocs 生成的网站。

截屏2025-02-03 11.13.14.png

这个页面是 MkDocs 自动生成的首页，内容是 docs/index.md 文件中的内容。你可以在这个文件中写入 Markdown 语法的内容，然后刷新页面，就能看到内容的变化。

按下 Ctrl + C 终止 mkdocs serve 命令。

网站内容和样式设置#

你可能会奇怪，为什么这个页面看起来和本站不一样？这是因为本站使用了 Material for MkDocs 主题。

同时，本站的文章内容也不是直接写在 docs/index.md 文件中的，而是在 docs 文件夹下的其他 Markdown 文件中的。这些文件会被 MkDocs 自动识别并生成对应的页面。

以上这些内容和样式的设置大多都集中在 mkdocs.yml 文件中，这个文件是 MkDocs 的配置文件，你可以在其中设置网站的标题、主题、导航栏等等。

下面给出一个简单的 mkdocs.yml 文件示例（也参考了其他人的代码）：

1
# [Info]
2
site_name: Fanovian's Notebook
3
site_url: https://note.fanovian.cc/
4
site_description: Fanovian 的笔记本
5

6
# [UI]
7
## [top]
8
theme:
9
  name: material
10
  custom_dir: overrides
11
  favicon: https://s2.loli.net/2025/01/27/oFMcIOLbZstxUjH.png
12
  font:
13
    text: LXGW WenKai Screen
14
    code: Maple Mono
15
  palette:
16
    # Palette toggle for automatic mode
17
    - media: "(prefers-color-scheme)"
18
      toggle:
19
        icon: material/auto-fix
20
        name: 切换至日间模式
21
    # Palette toggle for light mode
22
    - media: "(prefers-color-scheme: light)"
23
      scheme: default
24
      primary: var(--md-primary-fg-color)
25
      toggle:
26
        icon: material/toggle-switch
27
        name: 切换至夜间模式
28
    # Palette toggle for dark mode
29
    - media: "(prefers-color-scheme: dark)"
30
      scheme: slate
31
      primary: var(--md-primary-fg-color)
32
      toggle:
33
        icon: material/toggle-switch-off-outline
34
        name: 切换至跟随系统模式
35
  features:
36
    - announce.dismiss
37
    - navigation.tracking   #地址栏中的 URL 将自动更新为在目录中突出显示的活动锚点
38
    - navigation.tabs # 使用Tab来进行分类
39
    - navigation.top # 返回顶部的按钮 在上滑时出现
40
    - navigation.indexes # Tab会有一个index.md 而不是在打开Tab时打开第一篇文章
41
    # - navigation.footer # 底部的翻页
42
    # - navigation.expand # 打开Tab时左侧目录全部展开
43
    # - toc.follow
44
    - search.share   #搜索分享按钮
45
    - search.suggest # 搜索输入一些字母时推荐补全整个单词
46
    - search.highlight # 搜索出的文章关键词加入高亮
47
    - content.code.copy # 可以通过按钮复制代码
48
    - content.action.edit # 点击按钮跳转到编辑页面  需要结合 edit_uri 一起使用
49
  language: zh # 一些提示性的文字会变成中文
50
  icon:
51
    repo: fontawesome/brands/github
52
    logo: material/notebook
53
edit_uri: edit/main/docs # 编辑按钮跳转的链接
54

55
## [top-right corner]
56
repo_url: https://github.com/Fanovian/notebook # 右上角的GitHub链接
57
repo_name: Fanovian's Notebook # 鼠标悬浮提示
58

59
## [bottom-left corner]
60
copyright: Copyright &copy; 2023 - 2025 Fanovian
61

62
## [bottom-right corner]
63
extra:
64
  social: # icons
65
    - icon: fontawesome/solid/blog
66
      link: https://blog.fanovian.cc/
67
      name: Blog | Fanovian
68

69
# [Extensions]
70
plugins:
71
  - search:
72
      separator: '[\s\u200b\-]'
73
      lang:
74
        - en
75
        - ja
76
  - tags # 给单篇文章添加标签 https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/?h=tags
77

78
markdown_extensions:
79
  # - abbr
80
  - meta
81
  - def_list
82
  - attr_list
83
  # - admonition
84
  # - footnotes
85
  - md_in_html
86
  - sane_lists
87
  - admonition
88
  - pymdownx.keys
89
  - pymdownx.mark
90
  - pymdownx.tilde
91
  # - pymdownx.caret
92
  - pymdownx.critic
93
  # - pymdownx.betterem
94
  - pymdownx.details
95
  - pymdownx.snippets
96
  - pymdownx.magiclink
97
  - pymdownx.smartsymbols
98
  - pymdownx.superfences
99
  - pymdownx.inlinehilite
100
  # - markdown.extensions.attr_list
101
  - toc:
102
      permalink: true
103
      slugify: !!python/object/apply:pymdownx.slugs.slugify
104
        kwds:
105
          case: lower
106
      toc_depth: 4  # 将深度从 4 改为 2
107
  - pymdownx.superfences:
108
      custom_fences:
109
        - name: mermaid
110
          class: mermaid
111
          format: !!python/name:pymdownx.superfences.fence_code_format
112
  - pymdownx.highlight: # 代码块高亮
113
      anchor_linenums: true
114
      # linenums: true # 显示行号
115
      # auto_title: true # 显示编程语言名称
116
      linenums_style: pymdownx-inline
117
      line_spans: __span
118
      pygments_lang_class: true
119
  - pymdownx.emoji:
120
      emoji_index: !!python/name:material.extensions.emoji.twemoji
121
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
122
  - pymdownx.tabbed:
123
      alternate_style: true
124
  - pymdownx.tasklist:
125
      custom_checkbox: true
126
  - pymdownx.arithmatex:
127
      generic: true
128

129
extra_javascript:
130
  - https://polyfill.io/v3/polyfill.min.js?features=es6
131
  - javascripts/mathjax.js
132
  - https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js
133
extra_css:
134
  - stylesheets/extra.css
135
  - https://cdn.staticfile.org/font-awesome/4.7.0/css/font-awesome.css # font-awesome表情支持
136

137
# [Navigation]
138
nav:
139
  - 主页: index.md
140
  - 课程:
141
    - course/index.md
142
    - 程序设计与算法基础: course/fpa/final-exam-re.md
143
    - 数据结构基础:
144
      - course/fds/index.md
145
      - 算法分析基础: course/fds/ch1.md

nav、extra_css、extra_javascript 等地方引入文件的根目录是 docs 文件夹，所以你需要在 docs 文件夹下创建对应的文件夹，然后把文件放进去。

正如本文简介所言，文章不会大篇幅介绍这个配置的详细内容，因为 Material for MkDocs 的文档已经写得非常详细了，你可以在 Material for MkDocs 官网找到每一个字段的详细解释，也可以自己修改配置文件，然后刷新页面看效果。笔者认为新手的主要任务是先把网站跑起来，然后再慢慢调整样式。

除了动态预览，还可以终端输入：

1
mkdocs build

这个命令会在当前目录下生成一个 site 文件夹，里面包含了生成的静态网站文件，这个文件夹就是你需要部署到服务器上的文件夹。

部署到 GitHub Pages#

准备 GitHub 仓库#

首先要有一个 GitHub 账号，没有的自行搜索注册。

接着需要创建一个空仓库：

如果你打算只用一个仓库来存放网站源文件（也就是只有一个网站），那么仓库名应该是 username.github.io，其中 username 是你的 GitHub 用户名，这样就可以通过 https://username.github.io 来访问你的网站；
如果你打算有多个网站（比如笔者，一个是笔记本一个是博客），那么仓库名可以随意，但是需要在仓库的 Settings -> Pages 中进行一些设置，详情可以参考这篇文章：如何拥有多个GitHub Pages。这样设置后，需要通过 https://username.github.io/repo-name 来访问你的网站。

注册完之后，需要进行设置，让一会儿的 GitHub Actions 拥有权限来操作这个仓库。在 GitHub 仓库的 Settings -> Actions -> General 中的最下方 “Workflow permissions” 选项修改为 “Read and write permissions” 并保存。

Git 环境设置#

终端先进入网站根目录，然后执行：

1
git init
2
git branch -M main
3
git remote add origin https://github.com/username/repo-name.git

让 Git 管理这个文件夹，并且将默认分支改为 main，然后将这个文件夹与 GitHub 仓库关联。

自动部署命令#

我们每次有新内容 push 到 GitHub 仓库后，都需要手动执行 mkdocs gh-deploy 命令来部署网站，这样显然不够方便。为此我们利用 GitHub Actions 来实现自动部署。

创建目录和文件 .github/workflows/PublishMySite.yml，内容如下：

1
name: publish site
2
on:             # 工作流的触发条件
3
  push:         # 一种是本地 push 的时候
4
    branches:
5
      - main    # 只有在 main 分支 push 时才触发
6
  pull_request: # 另一种是 PR 合并时
7
    branches:
8
      - main
9
jobs:           # 工作流的具体内容
10
  deploy:
11
    runs-on: ubuntu-latest              # 创建一个新的云端虚拟机 使用最新 Ubuntu 系统
12
    steps:
13
      - uses: actions/checkout@v2       # 先 checkout 到 main 分支
14
      - uses: actions/setup-python@v2   # 再安装 Python3 和相关环境
15
        with:
16
          python-version: 3.x
17
      - run: pip install mkdocs-material # 使用 pip 包管理工具安装 mkdocs-material
18
      - run: mkdocs gh-deploy --force   # 使用 mkdocs-material 部署 gh-pages 分支

这个脚本文件实际上就是在操作“服务器”进行自动部署，当我们 push 代码到 GitHub 仓库的 main 分支时，GitHub Actions 会自动执行这个脚本，将网站部署到 GitHub Pages 上。

编辑好之后，网站的文件结构应该是这样的：

1
.
2
├── .github
3
│   └── workflows
4
│       └── PublishMySite.yml
5
├── docs
6
│   └── index.md
7
└── mkdocs.yml

其中 docs 文件夹里面是你自己的 Markdown 文件，也许不止一个。

提交并推送#

当做完你的网站内容时，执行：

1
git add .  # 添加所有文件到暂存区
2
git commit -m "Initial commit"  # 提交到本地仓库，引号内是提交信息
3
git push -u origin main  # 推送到远程仓库

push 完之后，可以进入 GitHub 仓库的 Actions 版块查看部署进度。如果发生错误，可以在 Actions 的日志中查看详细信息，你的邮箱也会收到错误信息。

大功告成#

一切正常的话，你的网站应该已经部署到了 GitHub Pages 上，可以通过 https://username.github.io 或者 https://username.github.io/repo-name 来访问你的网站了。