使用 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 文件，并通过添加以下行忽略 gem 锁定文件
```
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 网站添加内容”。

您可以向 GitHub Pages 网站添加 Jekyll 主题，以自定义网站的外观和风格。有关详细信息，请参阅“使用 Jekyll 向 GitHub Pages 网站添加主题”。