发布于 2025年2月21日
更新于 2026年8月11日
分类于编程
阅读时长 9 分钟

用 MkDocs 搭建个人网站¶

这是一份从本地建站、主题配置到线上部署的完整 MkDocs 实践记录。

1 所需环境¶

1) 一台电脑

常用设备，用于安装MkDocs、本地编写博客或文档，并保存网站源文件。

2) GitHub账号

备份代码，同时使用GitHub Pages部署网站。

3) 一台服务器（可选）

将网站部署在自己的服务器上。只有使用GitHub Pages时，不需要准备服务器。

4) 一个域名（可选）

GitHub Pages和服务器都会提供可以直接访问的地址。如果希望使用自己的网址，可以再购买并配置域名。

2 搭建思路¶

本网站的搭建方式分为三步：

1) 通过MkDocs在本地构建静态网站。

2) GitHub Pages部署网站：将网站源文件上传到GitHub，并通过GitHub Pages发布。

3) 服务器部署网站：将MkDocs生成的静态文件上传到服务器（可选）。

如果没有服务器，只需要实现1)和2)即可完成网站的部署。不过这种方法部署的网站托管在GitHub Pages上，部分网络环境下访问可能不够稳定。如果有服务器，可以继续实现3)，也可以同时保留GitHub Pages作为备用地址。

下面按照上面三个步骤的顺序进行说明。

3 通过MkDocs构建静态网站¶

3.1 基本Python环境配置¶

3.1.1 本地电脑安装MkDocs¶

MkDocs的安装需要Python环境，本文默认读者已经拥有了Python环境。可以先在终端检查Python和pip是否能够正常使用：

CMD

python --version
python -m pip --version

建议为网站创建单独的虚拟环境，避免不同项目的Python包相互影响：

Windows PowerShellLinux / macOS

python -m venv .venv
.\.venv\Scripts\Activate.ps1

python -m venv .venv
source .venv/bin/activate

安装MkDocs的Python包：

CMD

python -m pip install mkdocs

安装完成后，可以使用以下指令检查是否安装成功：

CMD

mkdocs --version

3.1.2 选择并安装一个主题¶

MkDocs内置了一些主题，也支持很多外部主题，各类主题的说明和安装可以详见官方指南。

本文推荐使用Material for MkDocs主题，安装指令为：

CMD

python -m pip install mkdocs-material

mkdocs-material会自动安装兼容的MkDocs及相关依赖，因此也可以直接安装它，不必重复执行上一节的pip install mkdocs。

如果网站还使用了其他插件，建议将依赖记录到requirements.txt中，方便在其他电脑或GitHub Actions中还原环境：

requirements.txt

mkdocs-material
# 其他插件继续写在下面

安装依赖文件中所有Python包的指令为：

CMD

python -m pip install -r requirements.txt

3.2 构建MkDocs网站根目录¶

进入安装MkDocs的Python环境，终端进入一个空文件夹作为网站的根目录，并生成基础文件：

生成网站目录

mkdocs new .

生成的文件结构如下：

.
├─ docs/
│  └─ index.md
└─ mkdocs.yml

mkdocs.yml：网站的配置文件，用来设置网站名称、主题、导航和插件等内容。
docs/：网站的源文件目录，Markdown文章、图片和其他资源都放在这里。
docs/index.md：网站首页，访问网站根地址时默认显示该文件。

3.3 完成MkDocs的一些基本设置¶

3.3.1 编写网站内容¶

MkDocs使用Markdown文件生成网页。在docs文件夹内新建.md文件，并使用普通Markdown语法编写内容即可。例如，新建docs/about.md：

docs/about.md

# 关于本站

这是我的第一个MkDocs网站。

图片等资源也应放在docs文件夹内。例如图片路径为docs/assets/brand/logo.png时，在文章中可以这样引用：

![网站Logo](/assets/brand/logo.png)

3.3.2 `mkdocs.yml`文件配置¶

mkdocs.yml使用YAML语法，缩进只能使用空格，不能使用Tab。一个可以直接运行的基础配置如下：

mkdocs.yml

site_name: My Website
site_url: https://username.github.io/repository/

theme:
  name: material
  language: zh

nav:
  - 首页: index.md
  - 关于: about.md

plugins:
  - search

其中，nav用来控制网站导航栏。配置文件中的文章路径以docs文件夹为起点，因此应填写about.md，而不是docs/about.md。

site_url的填写方法

如果仓库名为username.github.io，地址通常是https://username.github.io/；如果使用普通项目仓库，地址通常是https://username.github.io/repository/。配置自定义域名后，将site_url修改为自己的完整域名。

Material主题还支持颜色、字体、图标、搜索、博客等功能，后续可以根据主题配置文档逐步添加，不建议第一次配置时一次加入太多功能。

3.4 预览和生成网站¶

在mkdocs.yml所在目录执行以下指令，可以启动本地预览服务器：

1) 实时查看网站

mkdocs serve

浏览器打开终端显示的地址，默认是http://127.0.0.1:8000/。修改并保存文章后，页面会自动重新加载。

确认内容无误后生成静态网站文件：

2) 生成静态网站文件

mkdocs build --strict

生成的HTML、CSS和JavaScript文件默认保存在site文件夹内。--strict会将警告视为错误，适合在正式部署前检查无效链接和错误配置；如果正在整理旧文章，也可以暂时去掉该参数。

Warning

site文件夹是自动生成的，不要直接在里面修改文章。下一次执行mkdocs build时，其中的修改会被覆盖。

4 GitHub Pages部署网站¶

4.1 新建GitHub仓库¶

登录GitHub并创建一个新仓库。仓库名称有两种常见选择：

username.github.io：用户网站，默认地址为https://username.github.io/，每个账号只能创建一个。
其他名称：项目网站，默认地址为https://username.github.io/repository/。

如果本地已经存在完整的网站文件，创建仓库时可以不勾选自动生成README、.gitignore和许可证，避免第一次推送时出现无关的合并冲突。

4.2 将网站源文件上传到GitHub¶

在网站根目录，也就是mkdocs.yml所在目录执行：

初始化Git仓库

git init
git add .
git commit -m "Initial site"
git branch -M main
git remote add origin https://github.com/username/repository.git
git push -u origin main

将username和repository替换为自己的GitHub用户名和仓库名。

建议在.gitignore中忽略本地虚拟环境、缓存和自动生成的site文件夹：

.gitignore

.venv/
site/
__pycache__/

4.3 发布到GitHub Pages¶

手动发布GitHub Actions自动发布

在mkdocs.yml所在目录执行：

mkdocs gh-deploy --force

该指令会构建网站，并将结果推送到仓库的gh-pages分支。第一次运行后，进入GitHub仓库的「Settings -> Pages」，将发布方式设置为「Deploy from a branch」，选择gh-pages分支和/(root)目录，然后保存。

后续每次更新网站时，先提交源文件，再重新执行mkdocs gh-deploy --force即可。

如果希望每次推送main分支后自动发布，在网站根目录新建.github/workflows/ci.yml：

.github/workflows/ci.yml

name: ci

on:
  push:
    branches:
      - main

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: pip install -r requirements.txt
      - run: mkdocs gh-deploy --force

提交并推送该文件后，可以在仓库的「Actions」页面查看构建过程。构建完成后，同样在「Settings -> Pages」中确认发布分支为gh-pages。

Tip

GitHub Pages首次发布可能需要等待几分钟。如果页面没有出现，先查看「Actions」中是否有报错，再检查「Settings -> Pages」中的发布分支是否正确。

5 配置服务器¶

5.1 先拥有一台服务器¶

配置服务器的前提是先拥有一台服务器。很多平台都提供服务器租赁服务，比如华为云、阿里云、腾讯云等。各平台的学生优惠和促销活动经常变化，购买前应以官网的最新说明为准。

用于个人静态博客的服务器配置通常不需要太高，根据个人经验，只要满足以下条件就已经非常够用：

CPU内核数 \(\geqslant 1\)
内存 \(\geqslant 2\,\mathrm{GB}\)
存储空间 \(\geqslant 30\,\mathrm{GB}\)

选择系统时可以优先考虑仍在维护的Ubuntu或Debian版本。购买完成后，还需要在云平台的安全组中放行80端口；如果准备配置HTTPS，则同时放行443端口。

5.2 在服务器上安装宝塔¶

宝塔是一款方便配置站点环境的集成面板工具，对于不熟悉网站相关操作的新手来说比较友好。本文使用宝塔来配置服务器上所需要的相关环境。

先通过SSH登录服务器，再根据服务器系统从宝塔Linux面板下载页面复制最新的安装指令。官网当前提供的通用安装指令如下：

if [ -f /usr/bin/curl ];then curl -sSO https://download.bt.cn/install/install_panel.sh;else wget -O install_panel.sh https://download.bt.cn/install/install_panel.sh;fi;bash install_panel.sh ed8484bec

Warning

这条指令会从网络下载脚本并以服务器管理员权限执行。安装指令和支持的系统可能发生变化，实际操作时应从宝塔官网重新复制，并确认下载地址为官方域名。

安装完成后，终端会显示面板地址、用户名和密码。第一次登录后应立即修改默认用户名、密码和面板入口，并在云平台安全组中只对可信IP开放面板端口。

5.3 在宝塔面板配置服务器环境¶

MkDocs生成的是静态网站，只需要安装Nginx，不需要安装PHP和数据库。基本配置步骤如下：

1) 在宝塔的软件商店中安装Nginx。

2) 在域名服务商处添加A记录，将域名解析到服务器公网IP。如果暂时没有域名，也可以先使用IP地址测试。

3) 进入宝塔的「网站」页面并添加站点，填写域名，将站点根目录设置为/www/wwwroot/[webname]/。

4) 确认云平台安全组和服务器防火墙已经放行80、443端口。

5) 使用域名时，可以在站点的SSL设置中申请证书并开启HTTPS。证书生效前，应先确认域名已经正确解析到当前服务器。

其中，[webname]可以替换为域名或便于识别的站点名称。

5.4 将生成的文件上传服务器¶

生成的文件都在site文件夹内。将site文件夹中的所有文件上传至/www/wwwroot/[webname]/文件夹内，而不是把site文件夹本身再嵌套一层。

这里为了方便，可以直接通过宝塔文件管理器上传。其他方案，比如Termius或者VSCode通过SSH连接服务器上传也可以，目的是将生成后的文件同步到站点根目录。

上传后的结构大致如下：

/www/wwwroot/[webname]/
├─ index.html
├─ 404.html
├─ assets/
└─ ...

完成后访问服务器IP或域名。如果出现宝塔默认页面，检查站点根目录是否正确；如果页面能打开但样式丢失，检查mkdocs.yml中的site_url以及文件是否完整上传。

以后更新网站时，重新执行mkdocs build --strict，再将新的site目录内容覆盖上传即可。

6 实用小功能¶

以上就是搭建一个网站的所有内容了，正文内容到此就已经结束了。

本节内容是我在搭建网站时的一些常用小功能，做一个记录和分享。

6.1 创建一个「下载页面」¶

功能说明

「下载页面」能够列出一个文件夹内所有的文件，点击即可下载对应文件。该页面可以作为一个简易云盘使用。

假设在网站根目录中创建了一个download文件夹，即URL为域名/download/，则设置如下。

宝塔面板设置

在宝塔面板中，进入「网站 -> 设置 -> 配置文件」，在server内添加以下代码：

# download自动识别文件
location /download/ {
    autoindex on;
    autoindex_exact_size off;
    autoindex_localtime on;
    charset utf-8;
}

保存配置并重新加载Nginx，在该文件夹中放入文件，即可自动生成下载清单。

Warning

开启autoindex后，任何能够访问该地址的人都可以看到并下载目录中的文件。不要在该文件夹中放置密码、密钥、备份文件等敏感内容。

7 常见问题¶

7.1 本地可以访问，GitHub Pages样式丢失¶

普通项目仓库的地址中包含仓库名，需要确认site_url填写为https://username.github.io/repository/，然后重新构建和部署。

7.2 修改文章后网页没有变化¶

本地预览时确认mkdocs serve仍在运行，并尝试强制刷新浏览器。服务器部署时，需要重新执行mkdocs build并上传新的site目录内容；GitHub Pages部署时，需要重新运行部署指令或检查GitHub Actions。

7.3 执行`mkdocs`时提示找不到命令¶

先确认已经进入安装MkDocs的Python环境，再执行python -m pip show mkdocs检查安装位置。Windows用户也可以尝试使用python -m mkdocs serve代替mkdocs serve。

8 参考资料¹ ² ³ ⁴ ⁵ ⁶ ⁷ ⁸¶

2025-02-212026-08-11

尝试修改MkDocs Material网页字体的过程记录 —— Ranald Luo ↩
MkDocs Material超全配置 —— wnc的咖啡馆 ↩
Material for MkDocs: Setup —— Material官方教程 ↩
Google Fonts —— Google ↩
GitHub Pages快速入门 —— GitHub官方文档 ↩
Getting Started with MkDocs —— MkDocs官方文档 ↩
Publishing your site —— Material官方教程 ↩
宝塔Linux面板下载 —— 宝塔官网 ↩

用 MkDocs 搭建个人网站¶

1 所需环境¶

2 搭建思路¶

3 通过MkDocs构建静态网站¶

3.1 基本Python环境配置¶

3.1.1 本地电脑安装MkDocs¶

3.1.2 选择并安装一个主题¶

3.2 构建MkDocs网站根目录¶

3.3 完成MkDocs的一些基本设置¶

3.3.1 编写网站内容¶

3.3.2 mkdocs.yml文件配置¶

3.4 预览和生成网站¶

4 GitHub Pages部署网站¶

4.1 新建GitHub仓库¶

4.2 将网站源文件上传到GitHub¶

4.3 发布到GitHub Pages¶

5 配置服务器¶

5.1 先拥有一台服务器¶

5.2 在服务器上安装宝塔¶

5.3 在宝塔面板配置服务器环境¶

5.4 将生成的文件上传服务器¶

6 实用小功能¶

6.1 创建一个「下载页面」¶

7 常见问题¶

7.1 本地可以访问，GitHub Pages样式丢失¶

7.2 修改文章后网页没有变化¶

7.3 执行mkdocs时提示找不到命令¶

8 参考资料1 2 3 4 5 6 7 8¶

3.3.2 `mkdocs.yml`文件配置¶

7.3 执行`mkdocs`时提示找不到命令¶

8 参考资料¹ ² ³ ⁴ ⁵ ⁶ ⁷ ⁸¶