实际安装¶

记录时间：2025-05-06

本文记录基于 Windows + VS Code 环境，使用 MkDocs + Material 主题，从零开始搭建一个技术博客网站，并成功发布至 GitHub Pages + 自定义域名。

1. 需求分析¶

基于Markdown的
本地可编辑和维护，基于VScode编辑，方便编程和记录同时进行
能同步到云上，随时通过浏览器访问。
能自适应中各种终端设备

2. 方案对比¶

特性	Jekyll+Just The Docs	MkDocs + Material	Hexo	Hugo
语言依赖	Ruby	Python	Node.js	Go
本地运行支持	jekyll serve	mkdocs serve
主题美观性	简洁文档风	极美 Material 设计	多样主题	现代化
手机适配	响应式	响应式
插件生态	中等	小但现代化	多（不稳定）	中等

✅MkDocs + Material（本文选择）：
- 专为文档/知识库打造，现代化 UI，搜索强大
- 本地预览 mkdocs serve 快速、简洁
- 支持 dark mode，响应式体验优秀
- GitHub Actions 可自动部署至 GitHub Pages
- 需要 Python 环境

Jekyll + Just the Docs：
- GitHub Pages 原生支持，部署几乎零配置
- 结构适合技术笔记类博客
- Markdown 编写自然，支持本地运行
- 依赖 Ruby 环境，Windows 安装稍繁琐

3. 安装环境（Python + MkDocs）¶

安装 Python（适用于 Windows）
访问官网下载安装程序：Python下载
安装时请务必勾选：「Add Python to PATH」，再点击安装。
安装完成后，打开命令提示符（Win + R → 输入 cmd），输入：

python --version #输出类似：Python 3.12.x，表示安装成功。

2. 安装 MkDocs 和 Material 主题
- 在命令行中依次输入以下命令：

pip install mkdocs-material
pip install ghp-import 
mkdocs --version #显示如：mkdocs, version 1.x.x 表示成功。

4. 项目初始化¶

# 创建博客目录
cd D:/Study/WebStudyNote
mkdir MyBlog
cd MyBlog
# 初始化 MkDocs 项目
mkdocs new .

这会生成以下结构：

MyBlog/
├── docs/
│   └── index.md     ← 首页内容
└── mkdocs.yml       ← 配置文件

5. 修改 `mkdocs.yml`，添加主题支持和网站图标：¶

准备一个小图标文件（建议 32x32 或 64x64 的 .ico 文件），命名为：favicon.ico
放入你的项目目录下的 docs/ 文件夹
在 mkdocs.yml 文件中添加或修改如下内容：

site_name: MyBlog
theme:
  name: material # Material 主题支持
  favicon: favicon.ico # 添加网站图标

6. 本地预览与编辑¶

# 启动本地服务预览
mkdocs serve

- 浏览器中打开 http://127.0.0.1:8000。如果能看到一个首页，写着 "Welcome to MkDocs"，就表示部署成功。
- 编辑 docs/index.md 和新建如 docs/about.md 即可实时刷新浏览器查看效果。

7. 添加自定义页面¶

# 示例添加关于页面
docs/
├── index.md
└── about.md

- 请在 docs/ 目录中创建一个名为 about.md 的文件，并写入如下内容：

# 关于我：你好！我是 Simon，这是我的技术学习笔记站点。

- 在 mkdocs.yml 中配置导航（或使用插件自动导航）：

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

注释说明：
- nav 是用来配置导航栏的列表。
- 每一项是“页面标题: 对应的 Markdown 文件路径”。
- 修改完成后，请重新启动预览。

8. 部署至 GitHub Pages¶

提前准备
请先登录你的 GitHub 账户，创建一个公开仓库，例如命名为 myblog，不要勾选 README。创建完仓库后，复制你的仓库地址，例如：
```
https://github.com/your-username/myblog.git
```

在 PowerShell 执行以下命令：你当前路径应为：D: Study\MyBlog

# 初始化 git 并推送
git init
git remote add origin https://github.com/你的用户名/MyBlog.git
git add .
git commit -m "init blog"
git branch -M main
git push -u origin main

发布至 GitHub Pages：

# 构建 + 发布
mkdocs build
ghp-import -n -p -f site

GitHub Pages 设置：
Source: gh-pages 分支
自定义域名：你自己的域名xxx.com
勾选 Enforce HTTPS

9. 配置自定义域名（Cloudflare）¶

添加 docs/CNAME文件，CNAME 内容为：

你自己的域名xxx.com

Cloudflare 添加 DNS 记录：

类型	名称	内容	状态
CNAME	xxx	你仓库名称.github.io	DNS Only

启用 Cloudflare HTTPS：
Always Use HTTPS
Automatic HTTPS Rewrite

10. 自动目录导航 + 分类结构¶

自动导航插件推荐：

pip install mkdocs-awesome-pages-plugin

配置 mkdocs.yml：增加启用插件代码

plugins:
  - search
  - awesome-pages

docs/
├── dev/
│   ├── .pages ← 新增文件
│   └── python-101.md
├── life/
└── notes/

.pages 示例内容：

title: 技术开发
nav:
  - Python 入门: python-101.md

以上内容已经完成配置并成功运行。如有问题，欢迎联系我交流！