GitHub小白也能搞定！用Mkdocs+GitHub Pages快速搭建个人博客（2024最新版）

最新推荐文章于 2026-05-08 14:48:11 发布

原创最新推荐文章于 2026-05-08 14:48:11 发布 · 466 阅读

本内容遵循CC 4.0 BY-SA版权协议

GitHub小白也能搞定！用Mkdocs+GitHub Pages快速搭建个人博客（2024最新版）

你是不是也想过拥有一个属于自己的技术博客，用来记录学习心得、展示项目作品，或者只是单纯想在网上有个“小窝”？但一想到要买服务器、配置环境、写复杂的代码，就觉得头大，感觉那是专业开发者才能玩转的事情。如果你有这样的想法，那今天这篇文章就是为你准备的。我们将一起，用最简单、最直观的方式，在2024年，从零开始搭建一个既美观又专业的静态博客。整个过程，你甚至不需要离开浏览器太多，核心工具就是GitHub和一个叫MkDocs的框架。

别被“静态网站”、“部署”这些词吓到。你可以把它想象成用乐高积木搭房子：GitHub提供了免费的地皮和仓库（GitHub Pages），MkDocs则是一套设计精美、说明书清晰的乐高套装。我们要做的，就是跟着说明书，把积木一块块拼起来。最终，你会得到一个加载飞快、风格现代、完全受你控制的个人网站，并且完全免费。它非常适合用来搭建个人作品集、技术文档站、学习笔记库，或者任何你想分享给世界的内容。

下面，我们就手把手开始这场搭建之旅。我会尽量避开晦涩的术语，用最直白的语言和截图，带你走过每一个关键步骤，并重点解释那些新手最容易卡住的地方。

1. 从零开始：搭建前的思想准备与环境梳理

在动手敲任何命令之前，我们先花几分钟理清整个流程的脉络和核心工具。这能帮你建立全局观，知道每一步在做什么，而不是机械地复制粘贴。

我们的目标是：在本地电脑上写好网站内容（使用Markdown这种极其简单的标记语言），然后通过一个自动化流程，将其发布到互联网上（GitHub Pages服务）。整个过程涉及几个关键角色：

GitHub：我们的“大本营”。它既是代码仓库（存放网站所有源文件），也是免费的托管服务商（通过GitHub Pages提供网站访问地址）。
MkDocs：我们的“网站生成器”。它是一个用Python写的工具，核心功能是把你写的Markdown文档，转换成一整套具有导航、搜索、主题样式的静态HTML网页。
Material for MkDocs：这是MkDocs的一个主题。它基于Google的Material Design设计语言，颜值极高，开箱即用，是我们选择MkDocs的主要原因之一。
Git：版本控制工具。你可以把它理解成一个“时光机”和“协作神器”，能记录你文件的每一次改动。我们主要通过GitHub Desktop这个图形化客户端来使用它，极大降低学习成本。
GitHub Actions：这是GitHub提供的自动化“流水线”。我们配置好之后，每次你更新文章并推送到GitHub，它会自动在云端帮你重新构建并发布网站，完全无需手动干预。

整个流程可以简化为以下几步：

准备舞台：注册GitHub账号，安装必要的本地工具（GitHub Desktop, Python）。
创建仓库：在GitHub上创建一个特殊的仓库，它的名字决定了你未来网站的地址。
本地搭建：将仓库“克隆”到本地电脑，使用MkDocs初始化网站结构。
内容创作：在本地用Markdown写文章，并通过实时预览功能查看效果。
自动化部署：配置GitHub Actions工作流，实现“一键发布”。
访问网站：全世界都可以通过一个固定的网址访问你的博客了。

理清了思路，我们就可以挽起袖子，开始第一步了。

2. 实战第一步：注册账号与创建核心仓库

这是所有步骤的起点，也是最简单的一步，但仓库的命名有讲究，请务必注意。

2.1 获取你的“网络身份证”：GitHub账号

如果你还没有GitHub账号，请访问 github.com 进行注册。这个过程和注册任何一个社交网站没有区别，填写用户名、邮箱、密码即可。用户名请慎重选择，因为它会出现在你未来的项目链接和网站地址中。建议使用你的英文名、昵称或品牌名。

2.2 安装本地“遥控器”：GitHub Desktop

为了更轻松地管理本地文件和远程仓库的同步，我们使用GitHub Desktop。它把复杂的Git命令变成了直观的按钮和图形界面。

访问 desktop.github.com 下载对应你操作系统的安装包（Windows/macOS）。
像安装普通软件一样完成安装。
打开GitHub Desktop，用它登录你刚注册的GitHub账号。

2.3 创建那个“特殊”的仓库

这是关键一步。GitHub Pages服务对一个特定命名的仓库有特殊支持，能让你的网站直接通过 https://[你的用户名].github.io 访问。

登录GitHub网页，点击右上角“+”号，选择 “New repository”。
在“Repository name”输入框中，必须严格按照此格式填写：[你的GitHub用户名].github.io。例如，我的用户名是“wcowin”，那么我的仓库名就必须是 wcowin.github.io。

注意：这里的用户名必须和你注册的完全一致，包括大小写。这是GitHub Pages的硬性规定。
描述（Description）可以选填，比如“My personal blog”。
选择仓库为 Public（公开，这样才能免费使用Pages服务）。
不要勾选“Initialize this repository with a README”（我们用MkDocs来初始化）。
点击绿色的 “Create repository” 按钮。

至此，你在云端的地皮已经划好了。接下来，我们要把这块地“映射”到本地电脑上。

2.4 将仓库克隆到本地

“克隆”就是把云端仓库完整地复制一份到你的电脑上，之后你就在本地操作，再同步回去。

打开刚才创建的仓库页面，点击绿色的 “Code” 按钮，选择 “Open with GitHub Desktop”。
GitHub Desktop会自动启动，并弹出窗口让你选择本地存放路径。选择一个你熟悉的文件夹（例如“文档”或“项目”），然后点击“Clone”。
稍等片刻，克隆完成。现在你的电脑上就有了一个名为 [你的用户名].github.io 的文件夹，这就是你未来网站项目的根目录。

3. 构建网站骨架：初始化MkDocs与主题配置

现在，我们进入本地文件夹，开始用MkDocs搭建网站的骨架。这里需要用到命令行终端，但别担心，命令非常简单。

3.1 确保Python环境就绪

MkDocs基于Python，所以我们需要先确保电脑上有Python环境。打开终端（Windows用户可以用PowerShell或CMD，macOS/Linux用Terminal），输入以下命令检查：

python --version
# 或
python3 --version

如果显示了Python 3.x的版本号（如Python 3.9.6），说明已安装。如果没有，请前往 python.org 下载最新稳定版安装。安装时务必勾选“Add Python to PATH”，这样系统才能识别命令。

3.2 安装MkDocs及其Material主题

在你的项目根目录下打开终端。一个快速的方法是：在文件管理器中进入你的 [用户名].github.io 文件夹，然后在地址栏输入 cmd（Windows）或直接右键选择“在此处打开终端/PowerShell窗口”。

在终端中，依次执行以下两条命令：

pip install mkdocs
pip install mkdocs-material

第一条命令安装MkDocs核心，第二条命令安装我们选定的Material主题。安装完成后，可以用 mkdocs --version 验证。

3.3 创建你的第一个网站

还是在项目根目录的终端里，运行以下命令：

mkdocs new .

注意命令最后的那个点 .，它代表“当前目录”。这个命令会在当前目录下生成MkDocs网站的最基本结构。完成后，你的文件夹里会多出两个东西：

mkdocs.yml：这是网站的配置文件，相当于网站的大脑，控制着网站名称、主题、导航菜单等所有设置。
docs/ 文件夹：这是存放网站所有内容的地方。里面已经有一个 index.md 文件，这就是你网站的主页。

现在，一个最基础的网站已经创建好了。你可以立即在本地预览它：

mkdocs serve

终端会显示类似 Running at: http://127.0.0.1:8000/ 的信息。打开你的浏览器，访问这个地址，你就能看到一个非常简洁的、带有Material主题风格的页面了！mkdocs serve 命令会启动一个本地开发服务器，并且支持热重载——你修改 docs/ 下的任何Markdown文件并保存，浏览器页面会自动刷新，所见即所得。

3.4 进行最基础的网站配置

让我们先给网站起个名字，并确认主题。用任何文本编辑器（推荐VS Code、Sublime Text等）打开根目录下的 mkdocs.yml 文件。

你会看到初始内容可能很简单。我们将其修改为以下基础配置：

site_name: 我的技术小栈  # 你的网站名称
site_url: https://你的用户名.github.io  # 你的网站最终地址
site_author: 你的名字  # 作者名

theme:
  name: material  # 指定使用material主题

# 导航菜单配置
nav:
  - 首页: index.md
  # 未来可以在这里添加更多页面，例如：
  # - 文章: articles.md
  # - 关于: about.md

保存文件后，回到浏览器，刷新页面，你会发现网站标题和浏览器标签页标题都变成了“我的技术小栈”。恭喜，你的网站已经有了基本的身份信息！

4. 实现自动化魔法：配置GitHub Actions一键部署

到目前为止，网站还只存在于你的本地电脑。如何让它被全世界看到呢？这就需要部署。我们将使用GitHub Actions实现全自动部署：每当你写完文章，只需将改动“推送”到GitHub，剩下的构建和发布工作将全部由GitHub的服务器自动完成。

4.1 理解GitHub Actions工作流

GitHub Actions允许你创建自定义的自动化工作流程（Workflow）。我们将创建一个工作流，它会在你每次向主分支（main）推送代码时被触发，自动执行以下任务：

启动一个全新的Ubuntu系统环境。
拉取（checkout）你最新的代码。
安装Python和MkDocs环境。
运行 mkdocs gh-deploy 命令，将 docs/ 下的Markdown文件构建成静态网页，并推送到一个名为 gh-pages 的特殊分支。
GitHub Pages服务会自动从 gh-pages 分支获取内容，发布到你的网站。

4.2 创建工作流配置文件

在你的项目根目录下，需要创建一个特定路径和名称的文件。你可以手动创建文件夹和文件，但用终端命令更高效。在项目根目录打开终端，执行以下命令：

对于macOS/Linux用户：

mkdir -p .github/workflows
cd .github/workflows
touch publish.yml

对于Windows用户（PowerShell）：

New-Item -ItemType Directory -Force -Path .github/workflows
cd .github/workflows
New-Item -Name publish.yml

现在，用文本编辑器打开刚创建的 .github/workflows/publish.yml 文件，将以下内容完整复制进去：

name: Publish Site via MkDocs # 工作流的名称

on: # 定义触发条件
  push: # 当发生推送事件时
    branches: [ main ] # 并且是推送到 main 分支
  pull_request: # 或者当针对 main 分支创建拉取请求时（用于测试）
    branches: [ main ]

jobs: # 定义要执行的任务
  deploy: # 任务名称：deploy
    runs-on: ubuntu-latest # 在最新的Ubuntu系统环境中运行
    steps: # 任务的具体步骤
      - name: Checkout code # 步骤1：检出代码
        uses: actions/checkout@v3

      - name: Set up Python # 步骤2：设置Python环境
        uses: actions/setup-python@v4
        with:
          python-version: '3.x' # 使用3.x的最新稳定版

      - name: Install dependencies # 步骤3：安装依赖
        run: |
          pip install mkdocs
          pip install mkdocs-material

      - name: Deploy to GitHub Pages # 步骤4：部署到GitHub Pages
        run: mkdocs gh-deploy --force

这个配置文件就是一个“自动化脚本”，告诉GitHub Actions该做什么。保存这个文件。

4.3 一个至关重要的权限设置（新手必看！）

这是很多教程会忽略，但新手最容易失败的一步。GitHub Actions工作流在运行时，需要有权限将构建好的网站文件写入到你仓库的 gh-pages 分支。我们需要在仓库设置中开启这个写权限。

回到你的GitHub仓库页面。
点击顶部的 “Settings” 选项卡。
在左侧边栏找到 “Actions” -> “General”。
页面往下拉，找到 “Workflow permissions” 部分。
选择 “Read and write permissions”（读写权限）。
务必点击“Save”按钮保存设置！

提示：如果不进行这一步，自动化部署可能会失败，并提示“Permission denied”之类的错误。这一步确保了工作流有足够的权限创建和更新 gh-pages 分支。

4.4 提交并触发第一次自动化部署

现在，让我们把本地所有的改动（包括新创建的MkDocs网站文件和工作流配置文件）提交到GitHub，并触发第一次自动化构建。

打开GitHub Desktop。你应该能看到左侧列出了所有更改的文件（mkdocs.yml, docs/index.md, .github/workflows/publish.yml 等）。
在左下角的摘要框（Summary）里，填写本次提交的说明，例如“Initial commit: setup mkdocs and github actions”。
点击 “Commit to main” 按钮提交到本地仓库。
点击窗口右上方的 “Push origin” 按钮，将本地提交推送到GitHub远程仓库。

推送完成后，立刻访问你的GitHub仓库页面，点击顶部的 “Actions” 选项卡。你会看到一个名为“Publish Site via MkDocs”的工作流正在运行（黄色图标），稍等1-2分钟，它会变成绿色的勾，表示成功。

5. 访问成果与后续内容管理

当GitHub Actions工作流运行成功后，你的网站就已经上线了！

5.1 访问你的个人网站

打开浏览器，访问：https://[你的GitHub用户名].github.io。例如：https://wcowin.github.io。

你应该能看到和本地 mkdocs serve 预览时一模一样的网站，但现在它已经部署在公网上了。任何人都可以通过这个链接访问它。

5.2 如何发布新文章？

未来更新网站变得极其简单，遵循一个固定的写作-发布循环：

本地写作：在 docs/ 文件夹下创建新的 .md 文件（如 first-post.md），用Markdown语法撰写内容。
更新导航：编辑 mkdocs.yml 文件，在 nav: 部分添加新页面的链接，例如：
```
nav:
  - 首页: index.md
  - 第一篇文章: first-post.md
  - 关于我: about.md
```
本地预览：在终端运行 mkdocs serve，在 http://127.0.0.1:8000 检查文章样式和导航是否正确。
提交与推送：
- 在GitHub Desktop中，你会看到更改的文件。
- 填写提交摘要，点击“Commit to main”。
- 点击“Push origin”。
自动发布：推送后，GitHub Actions会自动触发，大约一分钟后，你的新文章就会出现在线上网站中。

5.3 探索Material主题的强大功能

Material for MkDocs主题提供了大量开箱即用的高级功能，你只需要在 mkdocs.yml 中简单配置即可启用：

社交链接：在配置中添加 repo_url 和 edit_uri，可以显示GitHub仓库链接和“编辑此页”按钮。
站点搜索：Material主题内置了即时搜索功能，无需额外配置。
代码高亮与复制：代码块自动高亮，并带有“复制到剪贴板”按钮。
内容标签页：可以将相关内容组织到标签页中。
警告框：使用 !!! note、!!! warning 等语法插入醒目的提示框。

一个功能更丰富的配置示例片段：

theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      accent: pink
  features:
    - navigation.tabs
    - navigation.sections
    - toc.integrate
    - search.suggest
    - search.highlight
    - content.code.copy

repo_url: https://github.com/你的用户名/你的用户名.github.io
edit_uri: edit/main/docs/

你可以访问 Material for MkDocs官网查看完整的配置指南和演示，慢慢将你的博客打磨得更加个性化。

整个过程走下来，你会发现搭建一个静态博客并没有想象中复杂。核心在于理解了“本地创作 -> Git管理 -> 自动化部署”这个流程。一旦这个流水线搭建完毕，你之后的所有精力都可以专注于最重要的事情——创作内容。每次写完文章，那个简单的“Push origin”操作，就像按下了一个发布世界的按钮，这种体验既神奇又高效。我的第一个用这种方法搭建的博客已经稳定运行了两年，期间除了偶尔更新主题配置，几乎没有维护成本。现在，轮到你了。

标签