使用 Jekyll 创建 GitHub Pages 网站

您可以使用 Jekyll 在新的或现有的仓库中创建 GitHub Pages 网站。

谁可以使用此功能？

拥有仓库管理员权限的人员可以使用 Jekyll 创建 GitHub Pages 网站。

GitHub Pages 可用于使用 GitHub Free 和 GitHub Free for organizations 的公共仓库，以及使用 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和私有仓库。有关更多信息，请参阅“GitHub 的计划”。

从 2024 年 6 月 30 日起，所有 GitHub Pages 构建都将使用 GitHub Actions。无需进行其他更改，但必须在您的仓库中启用 GitHub Actions 才能继续构建。有关启用 GitHub Actions 的更多信息，请参阅“管理仓库的 GitHub Actions 设置”。

平台导航

本文内容

注意：组织所有者可以限制从组织拥有的仓库发布 GitHub Pages 网站。有关更多信息，请参阅“管理组织的 GitHub Pages 网站发布”。

先决条件

在使用 Jekyll 创建 GitHub Pages 网站之前，您必须安装 Jekyll 和 Git。有关更多信息，请参阅 Jekyll 文档中的安装和“设置 Git”。

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

安装 Ruby。有关更多信息，请参阅 Ruby 文档中的“安装 Ruby”。
安装 Bundler。有关更多信息，请参阅“Bundler”。

提示：如果您在尝试使用 Bundler 安装 Jekyll 时看到 Ruby 错误，您可能需要使用包管理器（例如 RVM 或 Homebrew）来管理您的 Ruby 安装。有关更多信息，请参阅 Jekyll 文档中的“故障排除”。

为您的网站创建存储库

您可以为您的网站创建一个存储库或选择一个现有的存储库。

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

如果拥有该存储库的帐户使用 GitHub Free 或 GitHub Free for organizations，则该存储库必须是公开的。

如果您想在现有存储库中创建网站，请跳到“创建您的网站”部分。

在任何页面的右上角，选择，然后单击新建存储库。
使用所有者下拉菜单选择您要拥有该存储库的帐户。
为您的存储库输入一个名称和可选的描述。如果您正在创建用户或组织网站，您的存储库必须命名为<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 的最新支持版本。您可以在此处找到此版本：“依赖项版本”。

正确的 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 上，导航到您的网站的存储库。
在您的存储库名称下，单击设置。如果您看不到“设置”选项卡，请选择下拉菜单，然后单击设置。
在侧边栏的“代码和自动化”部分，单击 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 网站添加内容”。

您可以将 Jekyll 主题添加到您的 GitHub Pages 网站以自定义网站的外观和感觉。有关更多信息，请参阅“使用 Jekyll 向您的 GitHub Pages 网站添加主题”。