当前位置：首页 > ops >正文

利用 MkDocs 和 GitHub 部署个人博客网页

ops 2025/7/23 10:34:37

文章目录

- 1.在本地安装 Material for MkDocs
- 2.创建网站示例
- 3.发布网站到 GitHub Pages
- - 3.1 建立 GitHub 博客专用仓库
  - 3.2 配置 GitHub Actions 工作流
  - 3.3 更新远程仓库
- 总结

在数字化时代，拥有一个个人博客网站不仅能展示自己的想法与作品，还能提升个人品牌的影响力。本文将详细介绍如何利用 MkDocs 和 Material for MkDocs 创建一个现代化的静态网站，并通过 GitHub Pages 实现免费部署。无论你是技术爱好者还是想要分享生活点滴的创作者，这个简单高效的方法都能帮助你快速搭建属于自己的在线空间。以下内容将带你一步步完成从本地安装到线上发布的完整流程。

1.在本地安装 Material for MkDocs

Material for MkDocs 是一个基于 MkDocs 的现代化文档框架，而 MkDocs 本身是一个轻量级的静态网站生成器，特别适合用来创建项目文档或个人博客。它以 Markdown 文件为基础，将内容转化为美观、易读的 HTML 页面。Material for MkDocs 在此基础上提供了优雅的主题和丰富的功能，比如响应式设计、内置搜索等，让你的网站看起来更专业。

安装非常方便，打开终端，使用 pip 即可：
```
pip install mkdocs-material
```
这将自动安装所有兼容的依赖项版本：MkDocs、Markdown、Pygments 和 Python Markdown Extensions。Material for MkDocs 始终致力于支持这些依赖项的最新版本，因此无需单独安装这些包。

2.创建网站示例

安装完成后，你就可以开始搭建自己的网站了。MkDocs 提供了一个便捷的命令行工具，让你快速初始化项目结构。以下是具体操作步骤：

初始化项目：首先，选择一个你喜欢的工作目录，然后创建一个文件夹（例如 blog_site）作为博客的工作空间。进入该目录后，运行初始化命令：
```
mkdir blog_site && cd blog_site
mkdocs new .
```
mkdocs new . 会在当前目录下生成一个基础的项目结构。完成后你会看到如下文件布局：
```
.
├─ docs/
│  └─ index.md
└─ mkdocs.yml
```
其中，docs/ 内是存放的具体博客内容，使用 markdown 格式；mkdocs.yml 是网页的基本配置。
配置网站信息：打开 mkdocs.yml文件，用文本编辑器（如 VS Code 或 Notepad++）进行修改。以下是一个简单的配置示例：
```
site_name: yourname's blog
site_url: https://yourname.github.io
site_author: yourname
theme:name: material #主题
```
注意：我们将站点发布到 GitHub Pages 时，站点通常托管在子路径下，即 https://yourname.github.io ；material 是先前安装好的主题示例。
本地预览：配置完成后，你可以在本地测试网站效果。在 blog_site 目录下运行：
```
mkdocs serve
```
显示服务本地端口，这个网站就算是初步建好了，可以点击查看：
```
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.33 seconds
INFO    -  [18:21:09] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [18:21:09] Serving on http://127.0.0.1:8000/
```
这表示网站已在本地启动。打开浏览器，输入 http://127.0.0.1:8000/ ，你就能看到初步搭建的网站效果。如果修改了docs/ 中的 Markdown 文件，页面会自动刷新，可边写边预览。

3.发布网站到 GitHub Pages

接下来我们将它部署到 GitHub Pages 上，让全世界都能访问。GitHub Pages 是 GitHub 提供的一项免费服务，特别适合托管静态网站，而且与 GitHub 的版本控制功能无缝集成。

3.1 建立 GitHub 博客专用仓库

创建仓库：登录 GitHub，点击右上角的 “+” 号，选择 “New repository”。仓库名称需遵循特定格式：你的用户名.github.io，例如 Sun-Seeker.github.io。保持其他设置默认，然后点击 “Create repository”。

这个名称很重要，因为 GitHub Pages 会根据它自动生成你的网站地址，比如 https://yourname.github.io/。
注意到仓库名称中，名字即为左边 Owner 的名字。新建好以后，克隆仓库至本地：
```
git clone git@github.com:yourname/yourname.github.io.git
cd yourname.github.io.git
```

3.2 配置 GitHub Actions 工作流

为了简化部署，我们使用 GitHub Actions 自动将网站发布到 GitHub Pages。这是一种自动化工具，可以在每次推送代码时运行预定义脚本。

创建工作流文件：在仓库根目录下创建以下路径和文件：

mkdir .github && cd .github
mkdir workflows && cd workflows
sudo vim ci.yml

进入 .github/workflows/ci.yml，然后复制并粘贴以下内容：

name: ci 
on:push:branches:- master - main
permissions:contents: write
jobs:deploy:runs-on: ubuntu-lateststeps:- uses: actions/checkout@v4- name: Configure Git Credentialsrun: |git config user.name github-actions[bot]git config user.email 41898282+github-actions[bot]@users.noreply.github.com- uses: actions/setup-python@v4with:python-version: 3.x- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV - uses: actions/cache@v3with:key: mkdocs-material-${{ env.cache_id }}path: .cacherestore-keys: |mkdocs-material-- run: pip install mkdocs-material - run: mkdocs gh-deploy --force

ci.yml 为持续集成配置文件，其作用是：

在推送代码到 main 或 master 分支时触发。
使用 Ubuntu 环境，安装 Python 和 mkdocs-material。
执行 mkdocs gh-deploy，将网站构建并推送到 GitHub Pages 专用的 gh-pages 分支。

复制本地网站文件：将之前创建的 blog_site 文件夹内容复制到仓库目录：
```
cd  yourname.github.io.git
cp -r ../blog_site/* ./
```
到这里先检查一下你的目录结构, 目录树状图如下所示:

要注意mkdocs.yml 文件里的网站链接为 https://<仓库名>，正如 https://yourname.github.io/
```
$ tree -a
yourname.github.io
├── .github 
│   └── workflows
│       └── ci.yml
├── docs
│   └── index.md
└── mkdocs.yml
```
**重点-启用 Actions 权限：**Github仓库 setings/Actions/General 勾选这两项：

3.3 更新远程仓库

提交并推送：在本地仓库根目录下执行操作：由于 ci.yml 会为我们自动创建 gh-pages 分支，所以不用自行创建
```
git add .
git commit -m "更新了主页样式"
git push origin main
```
重点-配置 Pages 设置：去远程仓库的 setings/pages 选择下图示意的路径：
等待一会网址就出来了，你的网站就是：
```
https://<名字>.github.io/
```

总结

通过本文的步骤，你已经掌握了利用 MkDocs 和 Material for MkDocs 搭建个人博客网站的核心技能。

从本地安装依赖、初始化项目，到配置主题和内容，再到通过 GitHub Pages 和 GitHub Actions 实现自动化部署，整个过程既简单又高效。最终，你的博客以 https://<名字>.github.io/ 的形式成功上线，完全免费且易于维护。未来，你可以通过丰富 docs/ 文件夹中的 Markdown 内容，不断更新和完善你的网站，打造一个独具特色的个人数字家园。

查看全文

http://www.xdnf.cn/news/9235.html