使用 Jekyll 创建 GitHub Pages 网站

你可以使用 Jekyll 在新或现有存储库中创建 GitHub Pages 网站。

谁可以使用此功能？

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

GitHub Pages 可用于具有 GitHub 免费版和 GitHub 免费版（适用于组织）的公共存储库，以及具有 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 网站添加主题”。