使用 Github Pages 和 Jekyll/Chirpy 搭建个人博客

前言

本博客即采用 Jekyll Theme Chirpy 搭建, 并部署在 Github Pages 上; 通过阅读本文, 你将得以创建与本博客相似的个人博客网站.

本博客对 Chirpy 主题进行了一定的样式修改. 通过本文介绍的技术路线搭建出的最基本的博客样板是: https://chirpy.cotes.page/.

通过学习本文, 你不会了解如何购买和绑定类似 blog.kyee.top 的网址. 假设你的 Github 账户用户名为 ABC, 则你的博客会默认部署在网址 abc.github.io. 无论如何, 你的个人博客将可以被所有人公开访问 (即使在中国大陆).

为了完成搭建, 需要的前置知识与工具有:

• VPN/加速器. 这是为了在中国大陆更流畅地访问 Github 和其他相关技术网站.
• 一个免费的 Github 账户. 本文不会涉及如何注册. 正如前文所述, 如果你的 Github 用户名较为晦涩, 你的博客地址也会如此.

在本文中, 你不需要学会 Git 或进行本地开发. 所有操作都将在 Github 网页端进行.

参考资料

本文参考的以及你可以参考的资料有:

• Chirpy 官方博客教程: https://chirpy.cotes.page/posts/getting-started/.
• 菜鸟教程 - Markdown 教程: https://www.runoob.com/markdown/md-tutorial.html.

创建仓库

以后均假定你的 Github 用户名是 ABC. 由于网址不区分大小写, 你的仓库名称和部署到的网址应该为 abc.github.io. 在此处, 出现大小写不一致是正常现象.

访问 github.com 并首先登陆你的账号 ABC.

访问 Chirpy 主题的官方入门模板仓库 https://github.com/cotes2020/chirpy-starter. 在仓库界面的右上角, 点击 Use this template, 选择 Create a new repository. 此时你将会跳转到仓库创建界面.

在仓库创建页面中, 你必须填写的只有一条: General 这一节的 Repository name 条目. 你 必须 在该条目中填写 abc.github.io. 这与预期的博客地址相同.

下面的 Description 栏目可以留空, 也可以随意填写, 它与博客的内容与样式没有任何关系. 其他所有条目都应该保持默认, 特别地, Owner 必须是你的用户名 ABC, visibility 必须选择 Public.

最后, 点击右下角的绿色按钮 Create repository, 所需仓库即创建成功.

什么是仓库, 以及仓库页面

仓库创建完成后, 会自动跳转到仓库主页, 网址形如 https://github.com/ABC/abc.github.io/. 该页面的最顶端一行是网站的通用页首, 表示与你的账号有关的操作; 下面一行是仓库信息栏, 它应该包含诸如 Code, Issue, Actions, Settings 的许多选项. 目前, 你所在的应该是 Code 选项栏.

当位于仓库的 Code 栏目时, 页面的主体部分应该包含两部分, 第一部分是一些文件夹和文件的列表, 它们的名字有 _data, plugins, _posts, README.md, LICENSE, config.yml 等等. 第二部分是一段带格式文本, 即 README 的内容. 如果你根据本教程创建仓库, 它的开头应该是 “Chirpy Starter: A minimal, ready-to-use …”

Github 是一个 Git 仓库托管网站. Git 是用来管理不断更新的仓库的工具, 在本教程中, 你不需要理解 Git. 所谓的仓库, 基本上就是一个保存了代码和各类其他文件的文件夹; 同时, 它附带了各种属性, 可以配置 Github 提供的各种插件和功能.

在本教程中, 这个文件夹的地址不位于本地, 而是在 Github 的托管服务器上, 你可以通过访问 Github 来操作仓库及其中的文件. 刚刚提到的仓库主页的文件夹和文件就表示该仓库里保存的文件. 你可以点击文件夹图标来进入这个文件夹内部 (即 “子目录”), 可以点击文件图标来进入文件详情页面, 查看文件内容, 修改历史或修改文件.

关于如何修改文件, 上传新文件, 创建文件夹等, 后续章节会介绍.

为仓库配置 Github Pages 选项

为了使你刚创建的仓库具备通过 Github Pages 部署到公开网址的能力, 现在需要进行一些配置.

在你的仓库页面, 选择仓库信息栏中的最后一项 Settings. 此时页面应该发生变化, 左侧有一个非常长的选项栏.

在左侧栏目选择 Pages. 找到其中 Build and deployment 小标题下的 Source 条目, 将它从默认的 Deploy from a branch 修改为 Github Actions, 并等待修改生效.

修改生效后, 页面上部会出现一个小卡片, 写着 Your site is live at https://abc.github.io/. 这表明部署成功. 现在, 访问对应网址, 你应该可以看到一个内容不完整的博客页面.

配置博客信息

博客的基础信息保存在仓库中的文件 _config.yml 中. 找到该文件, 点击进入文件页面, 右上角有一个铅笔图标, 表示编辑, 点击按钮.

该配置文件使用 YAML 格式撰写. 注意, 在该格式中, # 后面的部分是注释, 不会被识别. 所以当你看到 # 开头的内容, 可以忽略它, 也可以当作提示阅读. 你也不应该在你创建的内容中引入 #.

_config.yml 由多个条目组成, 每个条目都有一个条目名在冒号前, 如 theme: jekyll-theme-chirpy 中, theme 就是条目名. 冒号后, 直到行末 (或直到第一个 # 出现) 是该条目的内容 (可能为空).

注意, 冒号后的部分可能被引号包裹, 此时条目的内容不包含引号, 比如, 第一行改成 theme: "jekyll-theme-chirpy" 也是可以的. 推荐用引号包裹比较长的内容.

此外, 有些条目可以有子条目, 比如:

social:
  name: Mr. ABC
  email: ...
  ...

...

其中的 name 和 email 的前面空了两格, 表示它们是 social 的子条目.

你需要配置的条目有:

• lang: 改成 zh-CN, 表示简体中文.
• timezone: 改成你的时区. 对于中国大陆用户一般填写 Asia/Shanghai.
• title: 博客标题. 会出现在标签页上, 以及博客左边栏上部, 头像的下面.
• tagline: 博客副标题. 会出现在博客左边栏上部, 标题的下面.
• description: 会显示在推送, 转发等场景. 可以留空, 也可以写一句博客简介. 注意这一条默认会跟着 >-, 这是 YAML 表示换行文本的特殊语法. 不能理解的话, 直接把它删掉, 留空或替换成你想输入的内容即可.
• url: 必须写你的博客网址, 如 https://abc.github.io. 不要多写或少写斜杠.
• baseurl: 必须留空.
• github: 在下面的 username 子条目中填写你的 Github 用户名, 如 ABC.
• twitter: 同上, 填写 Twitter 用户名. 如果不想填写, 建议将 twitter: 和下面的 username: 两行一块直接删掉.
• social: 下面有一些子项目:
  • name: 你的名字. 将会显示在所有文章的作者栏 (如果没有专门配置特定文章的 author 属性).
  • email: 你的邮箱. 会显示在博客左边栏下部的邮箱位置. 可以不填.
• theme_mode: dark 或者 light. 会决定你的博客是黑色主题还是白色主题. 可以都试试.

编辑完成后, 点击右上角的 Commit, 提交这次修改.

在 Github 上, 每一次对仓库的修改都是一次 commit. 一次 commit 包含 commit message 和可选的 commit description, 这可以帮助追踪对仓库的修改, 防止丢失关键的内容. 不过本文不会详细教学如何维护这些 commit.

点击按钮后, 弹出的窗口就是要求你输入本次 commit 的相关信息. 幸运的是, 如果你什么也不填, Github 也会帮你自动生成这些内容, 所以你可以直接点击 Commit changes 完成提交.

在一次 commit 完成后, Github Pages 的自动脚本将会运行编译部署等步骤. 一段时间后, 在页面的主体部分的上部, 你的头像右侧, 将会出现一个绿色的勾, 表示运行成功. 如果出现的不是勾, 而是一个红叉, 表示出现了问题. 如果是黄色圆圈, 表示运行尚未结束, 需要等待.

当部署完成后, 你可以访问 abc.github.io 检查网站是否已经成功部署. 此时, 网页上应该没有任何文章, 头像是空的, 左边栏有首页, 分类, 标签, 归档, 关于这五个栏目. 网站语言应该已经变为中文, 并且能够显示你填写的 title 和 tagline 内容.

注意, 每次访问更新后的网站时, 你可能需要通过 Ctrl+Shift+R 来清空缓存, 重新加载网页内容, 否则某些元素会显示为老版本. 当检测到任何新的 commit 时, Chirpy 也会自动跳出一个弹窗提示 “检测到新版本的内容”. 点击更新也可以刷新页面.

上传头像与图片

为了在博客网站上显示图片, 视频或其他媒体内容, 你必须首先将它们放到仓库中的 assets 目录. 为了管理方便, 一般将图片放置到 assets/img 子目录. 特别的, 网站徽标必须被放在 assets/img/favicons 子目录下.

上述文件夹可能在你的项目中尚不存在, 此时需要新建. Github 网页端不支持直接新建文件夹. 为此, 可以通过创建一个新文件, 把它的路径设置到尚未存在的文件夹中来迫使 Github 自动创建这个文件夹.

进入 assets 目录, 点击右上角的 Add file 并选择 Create new file. 此时, 会进入创建文件页面. 你不需要编辑下面的内容栏, 只需要在上面的 Name your file 空格处, 输入 img/.placeholder.

在这一步中, 你会注意到当你输入一个 / 时, 前面的部分 (img) 会变成路径的一部分, 即变为蓝色文字. 不用担心, 这是正常现象, 这说明 Github 检测到了创建的文件夹.

点击下面的 Commit, 同样, 可以选择留空提交信息自动生成, 也可以手动填写. 完成后, 你会发现 assets/img 目录已经出现了, 并且其中有你刚才创建的 .placeholder 空文件. 你最好不要删除这个文件, 否则全空的文件夹又会被 Github 自动删除.

接下来上传头像. 你需要首先选择一张头像图. 它的大小和分辨率并不重要, 最好选择较小, 较低分辨率的图片. 如果你有 PNG 或别的格式的图片, 最好把它转换成 JPEG 格式. 这是为了使文件的空间占用变小; 因为每次查看你的博客网站时, 这张图片都会加载; 如果文件空间占用过大, 则加载时间会增加. 必须把图片裁剪成正方形. 最终, 合理的图片大小是几百 KB.

接下来, 进入 assets/img 目录. 点击右上角的 Add file, 选择 Upload file, 把你选择的头像文件拖动进去, 等待绿色的上传进度条消失.

等待绿色进度条消失这一步很重要, 如果等待时间不够长, 后续 commit 将会失败, 显示 400. 你应该等待它完全消失, 而不是走到尽头. 即使上传没有真正完成, 下面的 Commit 按钮也是可点击状态, 但是点击后会发生 400 错误.

在确认你的文件已经上传完成后, 点击下方的按键提交修改. 以下假设你上传了名为 avatar.jpg 的图片到 assets/img 目录.

打开 _config.yml, 找到 avatar 这一条, 默认情况下, 冒号后面应该是空的. 现在写下 /assets/img/avatar.jpg, 注意不要增加或减少斜杠. 随后提交修改. 再次访问网站 (并刷新缓存), 则可以在左侧边栏最上方看到你的头像.

关于如何上传网站徽标, 以及如何在文章中包含图片, 将会在后面的章节介绍.

上传文章

创建文章

博客的所有文章都保存在 _post 子目录下. 不妨以你正在阅读的这篇文章为例. 发布这篇文章的日期是 2026 年 9 月 8 日, 且文章的标题是 使用 Github Pages 和 Jekyll/Chirpy 搭建个人博客.

首先, 你需要在 _posts 子目录下点击右上角 Add file, 选择 Create new file, 并将文件命名为 2026-09-08-使用-Github-Pages-和-Jekyll-Chirpy-搭建个人博客.md. 其中, 2026-09-08- 作为一个前缀是必要的, 它与博客系统的归档功能等有关. 后面的名称可以简略地写, 也可以被替换成一个编号 (如 2026-09-08-00001.md 等), 它与访问这篇文章时的网址有关.

接下来, 你需要填写文件内容. 一篇博文由两个部分构成: 元信息栏和正文. 具体地, 本文的源代码前几段形如:

---
title: "使用 Github Pages 和 Jekyll/Chirpy 搭建个人博客"
date: 2026-09-08
categories: ["技术分享"]
tags: ["Github Pages"]
description: "针对新手的个人博客搭建指南."
---

## 前言

本博客就是用 Jekyll Theme Chirpy 搭建的, 并部署在 Github Pages 上; 一般而言, 搭建成功后的效果与本博客基本相同.

......

开头的两个 --- 中间包裹的就是元信息栏. 后面的部分是正文文本. 正文用 Markdown 语言撰写, 下一节介绍.

元信息栏中有意义的内容有:

• title: 表示本文的标题. 会显示在主页, 分类页面等的卡片上.
• date: 表示本文的发布日期. 应该与文件名保持一致.
• categories: 这篇文章会被放在哪个分类中. 这个条目可以用逗号分隔写入多项, 但这并不表明一篇文章可以被同时放入两个分类. 如果你写下: ["技术分享", "网络技术"], 则系统会自动生成双层分类: “技术分享” 是一个大类, 而 “技术分享/网络技术” 是其中的一个小类. 目前 Chirpy 只支持写入两项, 也就是分类只能有两层. 左边栏 “分类” 页面按分类整理所有文章.
• tags: 这篇文章会被打上什么标签. 标签可以有多个 (也可以没有), 用逗号隔开即可. 在正文最后可以查看有本文有哪些标签. 左边栏 “标签” 页面按标签整理所有文章.
• description: 表示文章的摘要或简述. 在首页的文章卡片中会出现. 如果不写, 会自动摘取正文中的前几句. 如果你希望完全留空, 则必须放置一对空的双引号.
• author: 可以不写 (比如本文), 此时系统会自动填入先前 _config.yml 中 social/name 项的值. 如果你希望为某些文章添加特殊的作者, 则可以加入这一行.
• last_modified_at: 表示本文的最后一次修改日期. 可以不写 (比如本文), 此时如果这篇文章被第一次提交后没有经历修改, 则不显示修改日期; 否则按最后一次更新这篇文章内容的 commit 日期自动生成.

填写完元信息后, 文章就可以正常生成. 不过为了使它包含内容, 需要用 Markdown 语言编写正文.

管理文章的最佳实践

在开始学习如何使用 Markdown 撰写正文前, 有几条关于如何管理博客文章的建议.

首先, 使用分类功能来管理文章的文体, 作者, 写作目的等抽象特征. 比如你可以具有一些分类: “小说”“散文”“笔记”“分享”“影评”“读者投稿”, 等等. 而使用标签功能来管理内容. 比如标签可以有: “花”“百合”“少女乐队”等等. 博客最好有较少的分类和较多的标签.

其次, 忠实地填写文章的撰写日期. 它最好是第一次正式发布时的日期. 以后, 每一次你更新它时 (以发生 Git commit 为准), 系统会自动更改更新日期. 当你更新文章时, 最好不要悄无声息地删除或添加一些内容; 对于涉及内容的修改, 你应该留下一些简要记录, 使读者能更真实地理解文章的创建过程.

尽可能不要更新已经发布的文章的文件名, 这将会导致访问文章的网址失效. 如果网址失效, 读者可能在分享或保存这篇文章的过程中丢失访问它的途径, 这会使人困扰. 你可以选择直接将文章下架来进行修改; 重新上传时, 更新 (或期待自动更新) 修改日期, 而不改变发布日期和文件名. 最好也不要在没有明确提示的情况下修改标题. 这有助于读者确定他阅读过你的哪些作品.

撰写 Markdown 文本

现在, 你可以开始撰写博客的正文. 博客的正文部分用 Markdown 语言撰写. Markdown 是一类标记语言, 换句话说, 它包含了文本和文本的格式. 本文只提供关于 Markdown 语言的基本概述.

1. 标题: 用 # 开头的文字是标题. # 表示一级标题, ## 表示二级, 等等. 一般而言, 在博客中从二级标题开始用, 直到三级, 四级等. 因为一级标题太大了.
2. 分段: 在两段文本间放置一个空行将会自动分段. 如果不想分段, 但希望换行 (比如写诗), 则在一行末尾添加两个空格, 然后换行.
3. 分隔符: 用 --- 来创建一长条横线作为两节的分隔符.
4. 代码段和代码块. 在行内用两个 “`” 即反引号框住一段文字, 则可以将其转换成 代码文本. 在行间, 连续写三个反引号独占一行, 表示大型代码块的开头, 接下来撰写一些代码, 并同样用三个反引号作为代码段的结尾. 反引号在键盘左上角, ESC 的下面 (开启英文输入法).
5. 黑体与斜体: 用 ** 或者 __ 包裹文字 (像这样: **一段文字**) 会让它变成 粗体. 用 * 或者 _ 包裹文字 (像这样: _一段文字_) 会让它变成 斜体. 当然, 如果用 ***, ___ 包裹文字, 就会变成 粗斜体.
6. 插入超链接: 用尖括号 < 和 > 包裹网址, 可以引入链接, 像这样: https://www.baidu.com. 更好的做法是, 写这样的格式: [描述](网址), 例如 [百度](https://www.baidu.com) 会显示为: 百度.
7. 列表功能: 用 1. 开头的表示有序列表, 用 - 开头的表示无序列表. 列表可以嵌套.
8. 转义字符. 如果你希望输入上面用到过的某些标记字符, 如 `, <, #, * 等等, 则你需要用反斜杠 \ 放在它们前面. 比如: “\`” 会显示为 `, “\\” 会显示成 \.

关于 Markdown 语言, 你可以在 菜鸟教程 学到更多.

一般而言, 不推荐在 Github 网页端写作. 你应该写好一篇文章, 在本地利用 Markdown 编辑器调整格式并检查, 然后把代码复制到 Github 网页端, 配置元信息栏, 并 commit. 为此, 本文推荐几个常用的 Markdown 编辑器: VSCode (代码编辑器, 内置 Markdown 功能), StackEdit (网页端编辑器), MarkText (开源免费).

本节最后的部分是一段 Markdown 代码和渲染效果的示例.

# 标题

## 标题2

你好  
你好啊!

---

我是一个`小画家`.

是的, 我是 **一个小画家!**.

---

这是我的 [博客](blog.kyee.top).

---

1. 吃饭
1. 睡觉

- 必须
  - 吃饭
  - 睡觉
- 不能
  - 不吃饭
  - 不睡觉

会显示为:

标题

标题2

你好
你好啊!

---

我是一个小画家.

是的, 我是 一个小画家!.

---

这是我的 博客.

---

1. 吃饭
2. 睡觉

• 必须
  • 吃饭
  • 睡觉
• 不能
  • 不吃饭
  • 不睡觉

上传图片

正如 “上传头像” 一节所述, 为了在博客中显示图片, 你必须先将它上传到 assets/img 中. 假设你已经上传了一张图片 assets/img/2026/HelloWorld.png, 此时, 你只需要在一个独立的段落中写:

![](/assets/img/2026/HelloWorld.png){:width="100%"}

就可以插入这张图片. 当然, 为了调节图片的显示大小, 你可能需要调整后面的百分比数值.