使用MkDocs搭建静态网站并部署到GitHub Pages超详细教程

什么是MkDocs

MkDocs是一个用Python编写的静态网站生成器，特别适合创建项目文档或个人博客。它使用Markdown来编写内容，然后生成美观的HTML页面。相比其他静态网站生成器，MkDocs的优点在于：

• 简单易用：安装和配置非常 straightforward
• 主题丰富：默认提供多个美观的主题，还可以自定义
• 实时预览：内置开发服务器，修改内容后立即可以看到效果
• 搜索功能：自动为文档添加全文搜索能力
• 响应式设计：生成的网站在各种设备上都能良好显示

如果你想快速搭建一个文档网站或个人博客，MkDocs绝对是一个值得考虑的选择。

安装MkDocs

步骤1：安装Python

MkDocs是基于Python的，所以首先需要安装Python。你可以从Python官网下载最新版本的Python安装包。

安装完成后，可以在命令行中输入以下命令验证是否安装成功：

python --version
# 或者 python3 --version

步骤2：安装MkDocs

使用pip（Python的包管理工具）安装MkDocs：

pip install mkdocs
# 或者 pip3 install mkdocs

安装完成后，输入以下命令验证：

mkdocs --version

创建并配置MkDocs项目

步骤1：创建新项目

选择一个合适的目录，打开命令行，输入以下命令创建一个新的MkDocs项目：

mkdocs new my-docs

这个命令会创建一个名为my-docs的文件夹，里面包含MkDocs项目的基本结构：

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

步骤2：配置项目

进入项目目录：

cd my-docs

打开mkdocs.yml文件，这是MkDocs的配置文件。我们可以在这里设置网站标题、主题、导航等。

以下是一个基本的配置示例：

# 网站标题
site_name: 我的文档网站

# 网站主题
theme:
  name: material

# 网站导航
nav:
  - 首页: index.md
  - 关于: about.md
  - 教程: 
    - 教程1: tutorials/tutorial1.md
    - 教程2: tutorials/tutorial2.md

# 网站描述
description: 这是一个使用MkDocs创建的文档网站

# 作者信息
author: wutongxue132

# 版权信息
copyright: © 2025 wutongxue132

步骤3：添加内容

在docs目录下，你可以创建Markdown文件来添加网站内容。例如，创建一个about.md文件：

cd docs
 touch about.md

在about.md中添加内容：

# 关于本站

这是一个使用MkDocs创建的静态网站，用于展示我的项目文档和学习笔记。

步骤4：预览网站

使用以下命令启动MkDocs的开发服务器：

mkdocs serve

然后在浏览器中访问http://127.0.0.1:8000/，就可以看到你的网站了。开发服务器会实时监测文件变化，当你修改内容后，页面会自动刷新。

自定义网站主题

MkDocs默认提供了几个主题，其中material主题是最受欢迎的一个。如果没有在配置文件中指定主题，MkDocs会使用默认的mkdocs主题。

要使用material主题，需要先安装：

pip install mkdocs-material

然后在mkdocs.yml中配置：

theme:
  name: material
  palette:
    primary: blue
    accent: light blue
  font:
    text: Roboto
    code: Roboto Mono

material主题还有很多可定制的选项，比如添加logo、修改颜色、启用暗黑模式等。你可以参考Material for MkDocs文档了解更多细节。

部署到GitHub Pages

步骤1：创建GitHub仓库

首先，在GitHub上创建一个新的仓库。仓库名称可以是username.github.io（其中username是你的GitHub用户名），这样你的网站会被部署到https://username.github.io/。

步骤2：配置GitHub Pages

1. 打开你的GitHub仓库，点击Settings选项卡。
2. 在左侧导航栏中选择Pages。
3. 在Source部分，选择main分支（或其他你想部署的分支）和/root目录。
4. 点击Save按钮。

步骤3：生成并部署静态文件

使用以下命令生成静态文件：

mkdocs build

这个命令会在项目目录下生成一个site文件夹，里面包含所有的静态文件。

接下来，我们需要将这些静态文件推送到GitHub仓库。可以使用以下命令：

# 初始化git仓库（如果还没有）
git init
\# 添加远程仓库
git remote add origin https://github.com/username/username.github.io.git

# 添加所有文件
git add .

# 提交更改
git commit -m "Initial commit"

# 推送到GitHub
git push -u origin main

步骤4：自动部署（可选）

为了简化部署流程，我们可以使用GitHub Actions来实现自动部署。创建一个.github/workflows/deploy.yml文件，添加以下内容：

name: Deploy MkDocs site to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.9'
      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install mkdocs mkdocs-material
      - name: Build site
        run: mkdocs build
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site

这样，每当你向main分支推送代码时，GitHub Actions就会自动构建并部署你的网站。

常见问题与解决方法

1. 部署后网站显示404错误

• 检查GitHub Pages的配置是否正确，确保选择了正确的分支和目录。
• 确保site文件夹中的文件已经被推送到GitHub仓库。

2. 主题样式不生效

• 确保已经安装了相应的主题包（如mkdocs-material）。
• 检查mkdocs.yml中的主题配置是否正确。

3. 本地预览正常，部署后样式错乱

• 可能是因为路径问题，在mkdocs.yml中添加site_url配置：

site_url: https://username.github.io/

总结

MkDocs是一个简单易用但功能强大的静态网站生成器，特别适合创建文档网站和个人博客。通过本文的教程，你应该已经掌握了MkDocs的基本使用方法和部署到GitHub Pages的详细步骤。

如果你想进一步定制你的网站，可以参考MkDocs的官方文档和相关主题的文档。祝你创建出美观实用的静态网站！

如果你有任何问题或建议，欢迎在下方留言讨论。