使用 Jekyll 创建 GitHub Pages 站点

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

谁可以使用此功能？

People with admin permissions for a repository can create a GitHub Pages site with Jekyll.

GitHub Pages 适用于具有 GitHub Free 和组织的 GitHub Free 的公共存储库，以及具有 GitHub Pro、GitHub Team、GitHub Enterprise Cloud 和 GitHub Enterprise Server 的公共和专用存储库。 有关详细信息，请参阅“GitHub 的计划”。

GitHub Pages 现在使用 GitHub Actions 来执行 Jekyll 构建。 使用分支作为构建源时，如果要使用内置的 Jekyll 工作流，则必须在存储库中启用 GitHub Actions。 或者，如果 GitHub Actions 不可用或已禁用，则将 .nojekyll 文件添加到源分支的根目录将绕过 Jekyll 构建过程并直接部署内容。 有关 GitHub Actions 运行器的详细信息，请参阅“管理存储库的 GitHub Actions 设置”。

Platform navigation

本文内容

Note

组织所有者可以限制从组织拥有的存储库发布 GitHub Pages 站点。 有关详细信息，请参阅“管理组织的 GitHub Pages 站点发布”。

先决条件

必须安装 Jekyll 和 Git 后才可使用 Jekyll 创建 GitHub Pages 站点。 有关详细信息，请参阅 Jekyll 文档中的安装和“设置 Git”。

建议使用 Bundler 安装和运行 Jekyll。 Bundler 可管理 Ruby gem 依赖项，减少 Jekyll 构建错误和阻止环境相关的漏洞。 要安装 Bundler：

  1. 安装 Ruby。 有关详细信息，请参阅 Ruby 文档中的“安装 Ruby”。
  2. 安装 Bundler。 有关详细信息，请参阅“Bundler”。

Tip

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

为站点创建仓库

可以为站点创建存储库或选择现有存储库。

如果存储库中并非所有文件都与站点相关，且要为存储库创建 GitHub Pages 站点，则能够为站点配置发布源。 例如，可以使用专用分支和文件夹保存站点源文件，也可以使用自定义 GitHub Actions 工作流来生成和部署站点源文件。

如果拥有存储库的帐户使用组织的 GitHub Free 或 GitHub Free，存储库必须是公共的。

如果要在现有存储库中创建站点，请跳至“创建站点”一节。

  1. 在任何页面的右上角，选择 ，然后单击“新建存储库”。

    GitHub 下拉菜单的屏幕截图，其中显示了用于创建新项的选项。 菜单项“新建存储库”用深橙色框标出。

  2. 使用“所有者”下拉菜单选择你想要拥有存储库的帐户。

    新 GitHub 存储库的所有者菜单的屏幕截图。 菜单显示两个选项：“octocat”和“github”。

    Note

    如果你是 托管用户帐户，将只能从组织拥有的存储库发布 GitHub Pages 站点。 有关详细信息，请参阅“关于 GitHub Pages”。

  3. 输入仓库的名称和说明（可选）。 如果要创建用户或组织站点，则存储库必须命名为 <user>.github.io 或 <organization>.github.io。 如果您的用户或组织名称包含大写字母，您必须小写字母。 有关详细信息，请参阅“关于 GitHub Pages”。

    存储库中 GitHub Pages 设置的屏幕截图。 存储库名称字段包含文本“octocat.github.io”，并用深橙色框出。

  4. 选择仓库可见性。 有关详细信息，请参阅“关于仓库”。

创建站点

必须先在 GitHub Enterprise Cloud 上有站点的仓库，然后才可创建站点。 如果未在现有存储库中创建站点，请参阅“为站点创建存储库”。

Warning

除非你的企业使用 Enterprise Managed Users，否则默认情况下 GitHub Pages 站点可以在 Internet 上公开，即使该站点的存储库是私有的或内部的也是如此。 可以通过管理站点的访问控制来私下发布站点。 否则，如果站点的存储库中有敏感数据，你可能想要在发布前删除数据。 有关详细信息，请参阅“关于仓库”和“更改 GitHub Pages 站点的可见性”。

  1. 打开终端终端Git Bash。

  2. 如果还没有本地版存储，请导航到想要存储站点源文件的位置，将 PARENT-FOLDER 替换为要包含存储库文件夹的文件夹。

    cd PARENT-FOLDER

  3. 如果尚未初始化本地 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

  4. 将目录更改为仓库。

    $ cd REPOSITORY-NAME
# Changes the working directory

  5. 确定要使用的发布源。 有关详细信息，请参阅“配置 GitHub Pages 站点的发布源”。

  6. 导航到站点的发布来源。 有关详细信息，请参阅“配置 GitHub Pages 站点的发布源”。 例如，如果选择从默认分支上的 docs 文件夹发布站点，请创建目录并将目录更改为 docs 文件夹。

    $ mkdir docs
# Creates a new folder called docs
$ cd docs

    If you chose to publish your site from the gh-pages branch, create and checkout the gh-pages branch.

    $ 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

  7. 若要创建新的 Jekyll 站点，请在存储库根目录中使用 jekyll new 命令：

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

  8. 打开 Jekyll 创建的 Gemfile 文件。

  9. 将“#”添加到以 gem "jekyll" 开头的行首，以注释禁止此行。

  10. 编辑以 # 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 的依赖项。

  11. 保存并关闭 Gemfile。

  12. 从命令行中，运行 bundle install。

  13. 通过添加以下行打开 Jekyll 创建并忽略 gems 锁定文件的 .gitignore 文件：

    Gemfile.lock

  14. （可选）对 _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

  15. （可选）在本地测试您的站点。 有关详细信息，请参阅使用 Jekyll 在本地测试 GitHub Pages 站点。

  16. 添加并提交您的工作。

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

  17. 将 GitHub.com 上的存储库添加为远程存储库，将 将 USER 替换为拥有该存储库的帐户并将 REPOSITORY 替换为存储库名称。

    
$ git remote add origin https://github.com/USER/REPOSITORY.git

  18. 将存储库推送到 GitHub Enterprise Cloud，将 BRANCH 替换为所操作的分支的名称。

    git push -u origin BRANCH

  19. 配置发布源。 有关详细信息，请参阅“配置 GitHub Pages 站点的发布源”。

  20. 在 GitHub Enterprise Cloud 上，导航到站点的仓库。

  21. 在存储库名称下，单击 “设置”。 如果看不到“设置”选项卡，请选择“”下拉菜单，然后单击“设置”。

    存储库标头的屏幕截图，其中显示了选项卡。 “设置”选项卡以深橙色边框突出显示。

  22. 在边栏的“代码和自动化”部分中，单击“ Pages”。

  23. （可选）如果要从专用或内部存储库发布项目网站，请选择站点可见性。 在“GitHub Pages”下，选择可见性下拉菜单，然后选择“公开”或“私密”。

    GitHub 存储库中 Pages 设置的屏幕截图。 用于选择 Pages 站点的私密或公开可见性的菜单（标有“私密”）用深橙色框出。

    Note

    若要非公开发布 GitHub Pages 网站，组织必须使用 GitHub Enterprise Cloud。 有关如何免费试用 GitHub Enterprise Cloud 的详细信息，请参阅“设置 GitHub Enterprise Cloud 的试用版”。

  24. 若要查看已发布的网站，请在“GitHub Pages”下单击“ 访问网站”。

    GitHub Pages 确认消息的屏幕截图，其中列出了站点的 URL。 在 URL 右侧，标有“访问网站”的按钮用深橙色框出。

    Note

    对站点的更改在推送到 GitHub Enterprise Cloud 后，最长可能需要 10 分钟才会发布。 如果一小时后仍然在浏览器中看不到 GitHub Pages 站点更改，请参阅“关于 GitHub Pages 站点的 Jekyll 构建错误”。

  25. GitHub Pages 站点是使用 GitHub Actions 工作流生成和部署的。 有关详细信息，请参阅“查看工作流程运行历史记录”。

    Note

    GitHub Actions 对公共存储库是免费的。 如果专用存储库和内部存储库超出每月分配的免费分钟数，则会收取使用费。 有关详细信息，请参阅“使用限制、计费和管理”。

Note

  • 如果从分支进行发布且站点尚未自动发布，请确保具有管理员权限和经验证的电子邮件地址的人员已将站点推送到发布源。
  • 由使用 GITHUB_TOKEN 的 GitHub Actions 工作流推送的提交不会触发 GitHub Pages 生成。

后续步骤

若要向站点添加新页面或帖子，请参阅“使用 Jekyll 向 GitHub Pages 站点添加内容”。

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