使用 MkDocs + GitHub Pages 搭建技术博客

📅 创建时间：2025年10月26日
🎯 目标：搭建一个免费、美观、易维护的技术博客系统

📋 需求分析

核心需求

• ✅ 免费托管：使用 GitHub Pages 零成本托管
• ✅ Markdown 写作：使用熟悉的 Markdown 语法
• ✅ 自动部署：推送代码自动更新博客
• ✅ 美观主题：现代化的 Material Design 主题
• ✅ 跨平台编辑：Windows 和 Mac 都能方便编辑
• ✅ 版本控制：Git 管理，支持历史回溯

技术选型对比

方案	优点	缺点	适用场景
MkDocs Material	配置简单、主题美观、支持搜索	功能相对简单	✅ 技术文档、学习笔记
Jekyll	GitHub 原生支持	配置复杂、Ruby 环境	个人博客
Hexo	主题丰富、插件多	Node.js 环境、构建慢	个人博客
VuePress	现代化、Vue 生态	配置复杂	技术文档
Hugo	构建速度快	Go 模板语法	大型站点

最终选择：MkDocs + Material 主题（最适合技术笔记和文档）

---

🛠️ 技术栈

• 静态站点生成器：MkDocs v1.6+
• 主题：Material for MkDocs
• 托管平台：GitHub Pages
• 自动部署：GitHub Actions
• 本地编辑：Obsidian
• 版本控制：Git + GitHub

---

📂 项目结构

OpenTheDoor/
├── .github/
│   └── workflows/
│       └── deploy.yml          # GitHub Actions 部署配置
├── docs/                        # 所有文档内容
│   ├── index.md                # 博客首页
│   ├── auth/                   # 认证授权专题
│   ├── devops/                 # DevOps 专题
│   ├── stylesheets/
│   │   └── extra.css           # 自定义样式
│   └── javascripts/
│       └── mathjax.js          # 数学公式支持
├── mkdocs.yml                   # MkDocs 配置文件
├── .gitignore                   # Git 忽略配置
└── README.md                    # 项目说明

---

🚀 搭建步骤

第一步：创建 GitHub 仓库

1. 访问 GitHub 并登录
2. 点击右上角 + → New repository
3. 填写仓库信息：
4. Repository name: OpenTheDoor（你的仓库名）
5. Description: 技术知识库
6. 选择 Public（GitHub Pages 需要公开仓库）
7. 创建仓库

第二步：本地初始化项目

# 克隆仓库到本地
git clone https://github.com/yourusername/OpenTheDoor.git
cd OpenTheDoor

# 创建基本目录结构
mkdir -p docs/stylesheets docs/javascripts

第三步：创建 MkDocs 配置

创建 mkdocs.yml 文件：

site_name: OpenTheDoor 技术知识库
site_url: https://yourusername.github.io/OpenTheDoor/
site_description: 系统性学习与技能提升的技术知识库
site_author: yourusername

# Repository
repo_name: yourusername/OpenTheDoor
repo_url: https://github.com/yourusername/OpenTheDoor

# 文档目录
docs_dir: docs

theme:
  name: material
  language: zh
  palette:
    # 浅色模式
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: 切换到深色模式
    # 深色模式
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: 切换到浅色模式
  features:
    # 导航功能
    - navigation.tabs           # 顶部标签导航
    - navigation.sections       # 侧边栏分组
    - navigation.expand         # 默认展开所有导航项
    - navigation.top            # 返回顶部按钮
    - navigation.tracking       # 地址栏自动更新

    # 右侧目录功能
    - toc.follow                # 目录跟随滚动

    # 搜索功能
    - search.suggest            # 搜索建议
    - search.highlight          # 搜索高亮

    # 内容功能
    - content.code.copy         # 代码复制按钮

  icon:
    repo: fontawesome/brands/github

# 导航结构
nav:
  - 首页: index.md
  - 认证授权:
    - auth/README.md
    - 认证授权基础: auth/01-认证授权基础.md
    # ... 更多文章

# Markdown 扩展
markdown_extensions:
  - toc:
      permalink: true
      toc_depth: 3
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true
  - admonition
  - pymdownx.details

# 插件
plugins:
  - search:
      lang:
        - zh
        - en

# 额外配置
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/yourusername

第四步：创建 GitHub Actions 工作流

创建 .github/workflows/deploy.yml：

name: Deploy MkDocs to GitHub Pages

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: write

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout 代码
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: 配置 Git 信息
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com

      - name: 设置 Python 环境
        uses: actions/setup-python@v5
        with:
          python-version: 3.x

      - name: 安装 MkDocs Material
        run: pip install mkdocs-material

      - name: 部署到 GitHub Pages
        run: mkdocs gh-deploy --force

第五步：创建首页内容

创建 docs/index.md，写入你的博客首页内容。

第六步：配置 .gitignore

创建 .gitignore：

# Obsidian
.obsidian/

# Cursor
.cursor/

# MkDocs
site/
.cache/

# OS
.DS_Store
Thumbs.db

# IDE
.vscode/
.idea/

第七步：推送到 GitHub

git add .
git commit -m "初始提交：配置 MkDocs 博客"
git push origin main

第八步：配置 GitHub Pages

1. 访问仓库的 Settings → Pages
2. Build and deployment 部分：
3. Source: Deploy from a branch
4. Branch: gh-pages + / (root) ⚠️ 重要：选择 gh-pages 分支！
5. 点击 Save
6. 等待 2-3 分钟，访问 https://yourusername.github.io/OpenTheDoor/

---

🔧 常见问题与解决方案

问题 1：博客显示 404

原因： - GitHub Pages 配置错误（选择了 main 分支而不是 gh-pages） - 首次部署需要等待时间 - 浏览器缓存

解决方案： 1. 确认 Pages 配置：Branch 必须是 gh-pages 2. 等待 2-5 分钟让 GitHub 完成部署 3. 强制刷新浏览器：Ctrl + Shift + R (Windows) 或 Cmd + Shift + R (Mac) 4. 使用无痕模式访问

问题 2：Windows PowerShell 提交信息乱码

原因：PowerShell 默认编码问题

解决方案： 使用文件方式提交

# 将提交信息写入文件
echo "你的提交信息" | Out-File -Encoding UTF8 commit_msg.txt

# 从文件读取提交信息
git commit -F commit_msg.txt

# 删除临时文件
Remove-Item commit_msg.txt

或者使用英文提交信息：

git commit -m "Add new article"

问题 3：MkDocs 编译错误 "docs_dir 不能是根目录"

原因：MkDocs 要求文档必须在子目录中

解决方案： 使用标准的 docs/ 目录结构，不要设置 docs_dir: .

# ❌ 错误配置
docs_dir: .

# ✅ 正确配置
docs_dir: docs

问题 4：左侧导航或右侧目录不显示

原因：功能未启用

解决方案： 在 mkdocs.yml 的 theme.features 中添加：

features:
  - navigation.expand         # 左侧导航自动展开
  - toc.follow                # 右侧目录跟随滚动

---

🎨 自定义样式

添加自定义 CSS

创建 docs/stylesheets/extra.css：

/* 优化中文字体 */
body {
  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", 
               "Microsoft YaHei", "微软雅黑", sans-serif;
}

/* 代码块样式 */
.highlight code {
  font-family: 'Consolas', 'Monaco', 'Courier New', monospace;
  font-size: 0.9em;
}

在 mkdocs.yml 中引用：

extra_css:
  - stylesheets/extra.css

---

💻 跨平台同步方案

使用 Obsidian + Git

Windows 端配置

1. 下载安装 Obsidian
2. 打开 docs/ 目录作为 Obsidian 保险库
3. 安装 Obsidian Git 插件（可选，用于自动同步）

Mac 端配置

1. 下载安装 Obsidian（Mac 版）
2. 克隆仓库：

   cd ~/Documents
   git clone https://github.com/yourusername/OpenTheDoor.git
   

3. 在 Obsidian 中打开 docs/ 目录

自动同步配置（Obsidian Git 插件）

安装插件后，在设置中配置： - Vault backup interval: 10 分钟自动提交 - Auto pull interval: 5 分钟自动拉取 - Pull updates on startup: 启动时自动拉取

---

📝 日常使用流程

添加新文章

1. 在 docs/ 目录下创建 Markdown 文件
2. 在 mkdocs.yml 的 nav 部分添加导航链接
3. 提交并推送：

git add .
echo "添加新文章：XXX" | Out-File -Encoding UTF8 commit_msg.txt
git commit -F commit_msg.txt
Remove-Item commit_msg.txt
git push

1. 等待 2-3 分钟，博客自动更新

创建新专题

1. 在 docs/ 下创建新目录：

   mkdir docs/new-topic
   

2. 创建 README.md 作为专题索引

3. 在 mkdocs.yml 中添加导航：

   nav:
     - 首页: index.md
     - 新专题:
       - new-topic/README.md
       - 文章1: new-topic/01-article.md
   

---

🎯 最佳实践

1. 文件命名规范

docs/
├── index.md                    # 首页
├── topic-name/                 # 专题目录（小写，连字符分隔）
│   ├── README.md              # 专题索引
│   ├── 01-article-name.md     # 编号 + 描述性名称
│   └── 02-another-article.md

2. 内容组织原则

• ✅ 每个专题一个目录
• ✅ 使用数字编号确定文章顺序
• ✅ 文件名使用英文（避免 URL 编码问题）
• ✅ 标题可以使用中文（更友好）

3. 提交信息规范

feat: 添加新功能
fix: 修复问题
docs: 更新文档
style: 样式调整
refactor: 重构代码

4. 图片管理

在 docs/ 下创建 images/ 目录：

![图片描述](../images/topic/image-name.png)

---

📊 部署流程说明

自动部署流程图

1. 本地编辑 Markdown 文件
          ↓
2. git push 推送到 GitHub
          ↓
3. GitHub Actions 触发
          ↓
4. 安装 MkDocs Material
          ↓
5. 执行 mkdocs gh-deploy
          ↓
6. 构建静态网站并推送到 gh-pages 分支
          ↓
7. GitHub Pages 自动发布
          ↓
8. 博客更新完成！✅

关键点说明

1. 两个分支的作用：
2. main 分支：存放源文件（Markdown、配置文件）

3. gh-pages 分支：存放构建后的静态网站（HTML、CSS、JS）

4. 为什么要用 gh-pages 分支：

5. GitHub Actions 自动构建后推送到 gh-pages
6. GitHub Pages 从 gh-pages 分支读取网站文件

7. 源文件和构建产物分离，保持仓库整洁

8. 部署时间：

9. GitHub Actions 构建：约 30-60 秒
10. GitHub Pages 发布：约 1-3 分钟
11. 总计：约 2-5 分钟

---

🎓 学习收获

通过本次博客搭建，学到了：

技术层面

• ✅ MkDocs 静态站点生成器的使用
• ✅ GitHub Actions CI/CD 自动化部署
• ✅ GitHub Pages 免费托管服务
• ✅ Material Design 主题配置
• ✅ Markdown 高级语法和扩展

工程实践

• ✅ Git 分支管理和工作流
• ✅ 项目结构组织和文件命名规范
• ✅ 跨平台同步方案设计
• ✅ 问题排查和调试技巧

工具使用

• ✅ Obsidian 笔记管理
• ✅ Windows PowerShell 脚本
• ✅ VSCode / Cursor 开发环境

---

📚 参考资源

官方文档

• MkDocs 官方文档
• Material for MkDocs
• GitHub Pages 文档
• GitHub Actions 文档

有用的链接

• Markdown 语法指南
• Obsidian 官网
• Material Design Icons

---

🔮 后续优化计划

• 添加评论系统（Giscus / Utterances）
• 添加网站统计（Google Analytics）
• 配置自定义域名
• 优化 SEO
• 添加 RSS 订阅
• 集成全文搜索
• 添加暗色主题自定义配色

---

💬 总结

这次博客搭建经历了不少波折，主要踩坑点：

1. docs_dir 配置错误：一开始设置为根目录导致编译失败
2. GitHub Pages 分支选择：错误选择了 main 分支而不是 gh-pages
3. PowerShell 编码问题：中文提交信息乱码
4. 浏览器缓存：修改后需要强制刷新才能看到更新

但最终成功搭建了一个： - 🎨 美观：Material Design 主题 - 🚀 高效：自动部署，专注内容 - 💰 免费：GitHub Pages 零成本托管 - 🔄 跨平台：Windows/Mac 无缝切换 - 📱 响应式：支持移动端访问

希望这个文档能帮助你快速搭建自己的技术博客！

---

**🎉 开始你的写作之旅吧！** *"最好的学习方式就是分享和输出"*