使用 Jekyll 创建 GitHub Pages 站点

注意

虽然 github-pages gem 在某些工作流中仍受支持，但现在推荐使用 GitHub Actions 来部署和自动化 GitHub Pages 站点。

先决条件

在使用 Jekyll 创建 GitHub Pages 站点之前，您必须安装 Jekyll 和 Git。欲了解更多信息，请参阅 Jekyll 文档中的安装以及设置 Git。

我们建议使用 Bundler 来安装和运行 Jekyll。Bundler 管理 Ruby gem 依赖，减少 Jekyll 构建错误，并防止环境相关的 bug。要安装 Bundler

安装 Ruby。欲了解更多信息，请参阅 Ruby 文档中的 “安装 Ruby”。
安装 Bundler。欲了解更多信息，请参阅 Bundler。

提示

如果在使用 Bundler 安装 Jekyll 时看到 Ruby 错误，可能需要使用包管理器（如 RVM 或 Homebrew）来管理 Ruby 安装。欲了解更多信息，请参阅 Jekyll 文档中的故障排除。

为您的站点创建仓库

您可以为站点创建一个新仓库，或选择已有仓库。

如果您希望为一个仓库创建 GitHub Pages 站点，而该仓库中并非所有文件都与站点相关，您可以为站点配置发布源。例如，您可以使用专用的分支和文件夹来存放站点源文件，或者使用自定义的 GitHub Actions 工作流来构建并部署站点源文件。

如果拥有该仓库的账户使用 GitHub Free 或面向组织的 GitHub Free，则仓库必须是公开的。

如果您想在已有仓库中创建站点，请跳转至创建站点部分。

在任意页面的右上角，选择，然后点击 新建仓库。
使用 Owner（所有者）下拉菜单选择您希望拥有该仓库的账户。
为您的仓库输入名称及可选的描述。如果您正在创建用户或组织站点，仓库必须命名为 <user>.github.io 或 <organization>.github.io。如果您的用户或组织名称中包含大写字母，必须将其转换为小写。更多信息，请参阅 GitHub Pages 是什么？。
选择仓库可见性。欲了解更多信息，请参阅关于仓库。

创建站点

在创建站点之前，您必须在 GitHub 上拥有该站点的仓库。如果您不是在已有仓库中创建站点，请参阅为站点创建仓库。

警告

GitHub Pages 站点在互联网上公开可访问，即使站点的仓库是私有的（前提是您的计划或组织允许）。如果您的站点仓库中包含敏感数据，您可能希望在发布前将其移除。更多信息，请参阅关于仓库。

打开终端终端Git Bash。
如果您尚未拥有仓库的本地副本，请前往您想存放站点源文件的位置，将 PARENT-FOLDER 替换为您希望包含仓库文件夹的父文件夹。
```
cd PARENT-FOLDER
```

如果尚未初始化本地 Git 仓库，请执行初始化操作，将 REPOSITORY-NAME 替换为您的仓库名称。

git init REPOSITORY-NAME
> Initialized empty Git repository in /REPOSITORY-NAME/.git/
# Creates a new folder on your computer, initialized as a Git repository

切换目录至该仓库。

cd REPOSITORY-NAME
# Changes the working directory

决定您想使用的发布源。更多信息，请参阅配置 GitHub Pages 站点的发布源。

前往站点的发布源。更多信息，请参阅配置 GitHub Pages 站点的发布源。例如，如果您选择从默认分支的 docs 文件夹发布站点，请创建并切换到该 docs 文件夹。

mkdir docs
# Creates a new folder called docs
cd docs

如果您选择从 gh-pages 分支发布站点，请创建并检出 gh-pages 分支。

git checkout --orphan gh-pages
# Creates a new branch, with no history or contents, called gh-pages, and switches to the gh-pages branch
git rm -rf .
# Removes the contents from your default branch from the working directory

要创建新的 Jekyll 站点，请在仓库根目录使用 jekyll new 命令。

jekyll new --skip-bundle .
# Creates a Jekyll site in the current directory

打开 Jekyll 创建的 Gemfile。
在以 gem "jekyll" 开头的行前加上 “#”，将其注释掉。
通过编辑以 # gem "github-pages" 开头的行来添加 github-pages gem。将此行更改为
```
gem "github-pages", "~> GITHUB-PAGES-VERSION", group: :jekyll_plugins
```
将 GITHUB-PAGES-VERSION 替换为 github-pages gem 的最新支持版本。您可以在此处找到该版本：Dependency versions（依赖版本）。

Jekyll 将作为 github-pages gem 的依赖被安装，使用正确的版本。
保存并关闭 Gemfile。
在命令行运行 bundle install。
打开 Jekyll 创建的 .gitignore 文件，并通过添加以下行来忽略 gems 锁文件：
```
Gemfile.lock
```

可选地，对 _config.yml 文件进行必要的编辑。当仓库托管在子目录中时，需要这样做以处理相对路径。更多信息，请参阅将子文件夹拆分为新仓库。

domain: my-site.github.io       # if you want to force HTTPS, specify the domain without the http at the start, e.g. example.com
url: https://my-site.github.io  # the base hostname and protocol for your site, e.g. http://example.com
baseurl: /REPOSITORY-NAME/      # place folder name if the site is served in a subfolder

可选地，在本地测试您的站点。更多信息，请参阅使用 Jekyll 在本地测试 GitHub Pages 站点。

添加并提交您的更改。

git add .
git commit -m 'Initial GitHub pages site with Jekyll'

在 GitHub.com 上将您的仓库添加为远程，需将 USER 替换为拥有仓库的账户，将 REPOSITORY 替换为仓库名称。
```
git remote add origin https://github.com/USER/REPOSITORY.git
```
将仓库推送到 GitHub，需将 BRANCH 替换为您正在使用的分支名称。
```
git push -u origin BRANCH
```
配置您的发布源。更多信息，请参阅配置 GitHub Pages 站点的发布源。
在 GitHub 上，前往您站点的仓库。
在您的仓库名称下，点击设置。如果看不到 “Settings（设置）” 选项卡，请选择下拉菜单，然后点击设置。
在侧边栏的“代码和自动化”部分，点击 Pages。
要查看已发布的站点，在 “GitHub Pages” 下，点击 访问站点。

注意

在您将更改推送至 GitHub 后，站点的更改可能需要长达 10 分钟才能发布。如果在一小时后仍未在浏览器中看到 GitHub Pages 站点的更改，请参阅关于 GitHub Pages 站点的 Jekyll 构建错误。
您的 GitHub Pages 站点使用 GitHub Actions 工作流进行构建和部署。更多信息，请参阅查看工作流运行历史。

注意

GitHub Actions 对公开仓库免费。对于超过每月免费分钟配额的私有和内部仓库，将按使用量收费。更多信息，请参阅计费与使用。

注意

如果您从分支发布且站点未自动发布，请确保具有管理员权限且已验证电子邮件地址的用户已向发布源推送。
使用 GITHUB_TOKEN 的 GitHub Actions 工作流推送的提交不会触发 GitHub Pages 构建。

后续步骤

要向站点添加新页面或文章，请参阅使用 Jekyll 向 GitHub Pages 站点添加内容。

您可以为 GitHub Pages 站点添加 Jekyll 主题，以自定义站点的外观和感觉。更多信息，请参阅使用 Jekyll 为 GitHub Pages 站点添加主题。

谁可以使用此功能？

平台导航

本文内容

先决条件

为您的站点创建仓库

创建站点

后续步骤