快速上手

创建站点仓库

创建站点仓库时有两种方案，可以按需选择：

方案 1：使用模板仓库（推荐）

该方案便于后续升级主题，隔离无关文件，适合只想专注写文章、尽量少配置的用户。

1. 登录 GitHub，进入 starter 模板仓库
2. 点击 Use this template（使用此模板），选择「Create a new repository（创建新仓库）」
3. 仓库命名为 <username>.github.io，username 替换为小写的 GitHub 用户名

方案 2：Fork 主题仓库

适合深度修改主题功能、界面样式，但后续升级主题会比较麻烦。除非熟悉 Jekyll，并且打算大量改动主题代码，否则不推荐此方式。

1. 登录 GitHub
2. Fork 主题主仓库
3. 将 Fork 得到的仓库命名为 <username>.github.io，username 替换为小写的 GitHub 用户名

---

配置开发环境

仓库创建完成后，搭建本地开发环境，主要有两种方式：

使用 Dev Containers（Windows 用户推荐）

Dev Containers 基于 Docker 提供隔离环境，不会污染本机系统，所有依赖都在容器内管理。

操作步骤

1. 安装 Docker
   • Windows /macOS：安装 Docker Desktop
   • Linux：安装 Docker Engine
2. 安装 VS Code 和 Dev Containers 扩展
3. 克隆仓库：
   • Docker Desktop：启动 VS Code，参考官方文档：在隔离容器环境打开 Git 仓库 / GitHub PR
   • Docker Engine：先把仓库克隆到本地，再用 VS Code 在容器中打开本地文件夹
4. 等待 Dev Containers 自动完成环境初始化

本机原生环境部署（类 Unix 系统推荐）

类 Unix 系统可以直接在本机搭建环境，性能更好；当然也可以选择 Dev Containers。

操作步骤

1. 按照 Jekyll 安装文档 安装 Jekyll，同时确保已安装 Git
2. 将仓库克隆到本地电脑
3. 如果是 Fork 主题的方式：安装 Node.js，在项目根目录执行 bash tools/init.sh 初始化仓库
4. 在项目根目录执行 bundle install 安装项目依赖

---

使用方法

启动 Jekyll 本地服务

在本地预览网站，执行下面命令：

$ bundle exec jekyll serve

如果你使用 Dev Containers，必须在 VS Code 的内置终端执行该命令。

等待几秒后，本地站点访问地址：http://127.0.0.1:4000

基础配置

按需修改 _config.yml 中的配置项，常用配置：

• url：网站域名
• avatar：头像
• timezone：时区
• lang：网站语言

社交联系方式

侧边栏底部会展示社交账号，可在 _data/contact.yml 文件里开启 / 关闭各个社交入口。

自定义样式表

自定义 CSS 样式：把主题内的 assets/css/jekyll-theme-chirpy.scss 复制到你的站点同路径下，在文件末尾添加自定义样式代码。

自定义静态资源

静态资源配置从 5.1.0 版本开始支持。静态资源 CDN 配置写在 _data/origin/cors.yml。你可以根据网站部署地区的网络情况替换部分资源地址。

如果你想把静态资源托管在自己服务器，可以参考仓库：chirpy-static-assets

---

部署网站

部署前检查 _config.yml，保证 url 参数配置正确。

如果你创建的是项目站点（不是个人主页仓库）、不使用自定义域名，或者要部署到 GitHub Pages 以外的服务器并需要子路径访问，务必设置 baseurl，值以斜杠开头，例如 /project-name。

下面任选一种方式部署 Jekyll 站点：

使用 GitHub Actions 部署

准备工作：

• GitHub 免费版：站点仓库必须设为公开
• 如果已经把 Gemfile.lock 提交到仓库，且本机不是 Linux 系统，需要更新 lock 文件平台列表：

$ bundle lock --add-platform x86_64-linux

接下来配置 Pages 服务：

1. 进入你的 GitHub 仓库，打开 Settings，左侧菜单找到 Pages。在「Build and deployment（构建与部署）」→「Source（来源）」下拉框，选择 GitHub Actions
2. 向仓库推送代码，触发 Actions 工作流。进入仓库 Actions 标签页，可以看到 Build and Deploy 任务运行。构建成功后网站自动上线。

完成后访问 GitHub 提供的站点链接即可。

本地构建 + 手动部署

适用于自建服务器：在本地打包网站静态文件，然后上传到服务器。

进入源码项目根目录，执行构建命令：

$ JEKYLL_ENV=production bundle exec jekyll b

如果没有指定输出路径，打包生成的静态文件会放在项目根目录的 _site 文件夹，把该目录全部上传到目标服务器即可。