我们经常发布文档更新,此页面的翻译可能仍在进行中。有关最新信息,请访问英文文档。如果此页面上的翻译有问题,请告诉我们

使用 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 Pages 站点的发布”。

基本要求

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

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

  1. 安装 Ruby。 更多信息请参阅 Ruby 文档中的“安装 Ruby”。
  2. 安装 Bundler。 更多信息请参阅“Bundler”。

提示:如果您在尝试使用 Bundler 安装 Jekyll 时看到 Ruby 错误,您可能需要使用包管理器(例如 RVMHomebrew)来管理您的 Ruby 安装。 更多信息请参阅 Jekyll 文档中的“故障排除”。

为站点创建仓库

如果站点是一个独立的项目,您可以创建新仓库来存储站点源代码。 如果您的站点与现有的项目关联,您可以添加站点的源代码添加到该项目仓库的默认分支或其他分支上的 /docs 文件夹中。 例如,如果您创建站点来发布已经在 GitHub 中的项目文档, 您可能想要将站点的源代码存储在与项目相同的仓库中。

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

  1. 在任何页面的右上角,使用 下拉菜单选择 New repository(新建仓库)带有创建新仓库选项的下拉菜单
  2. 使用 Owner(所有者)下拉菜单选择你想要拥有仓库的帐户。 所有者下拉菜单
  3. 输入仓库的名称和说明(可选)。 如果您创建的是用户或组织站点,仓库名称必须为 <user>.github.io<organization>.github.io。 更多信息请参阅“关于 GitHub Pages”。 创建仓库字段
  4. 选择仓库可见性。 更多信息请参阅“关于仓库可见性”。 选择仓库可见性的单选按钮

创建站点

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

警告:GitHub Pages 站点 默认在互联网上公开,即使站点的仓库是私有或内部的。 如果您的项目站点是从使用 GitHub Enterprise Cloud 的组织拥有的私有或内部仓库发布的,您可以管理站点的访问控制。 否则,如果 您的站点仓库中有敏感数据,则您可能要在发布前删除该数据。 更多信息请参阅“关于仓库可见性”和“更改 GitHub Pages 站点的可见性”。

  1. 打开 Terminal(终端)Terminal(终端)Git Bash

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

    $ cd PARENT-FOLDER
  3. 如果尚未初始化本地 Git 仓库,请将 REPOSITORY-NAME 替换为仓库名称。

    $ git init REPOSITORY-NAME
    > Initialized empty Git repository in /Users/octocat/my-site/.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

    如果选择从 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
  7. 要创建新 Jekyll 站点,请使用 jekyll new 命令:

    $ jekyll new .
    # 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 update

  13. (可选)在本地测试您的站点。 更多信息请参阅“使用 Jekyll 在本地测试 GitHub Pages 站点”。

  14. 将您的 GitHub 仓库添加为远程仓库,将 USER 替换为拥有该仓库的帐户并将 REPOSITORY 替换为仓库名称。

    $ git remote add origin https://github.com/USER/REPOSITORY.git
    
  15. 将仓库推送到 GitHub,BRANCH 替换为您所操作的分支的名称。

    $ git push -u origin BRANCH
  16. 配置发布源。 更多信息请参阅“配置 GitHub Pages 站点的发布来源”。

  17. 在 GitHub 上,导航到站点的仓库。

  18. 在仓库名称下,单击 Settings(设置)仓库设置按钮

  19. 在左侧边栏中,单击 Pages(页面)Page tab in the left-hand sidebar

  20. (可选)如果您使用 GitHub Enterprise Cloud 从组织拥有的私有或内部仓库发布项目站点,请选择站点的可见性。 在 "GitHub Pages" 下,选择 GitHub Pages visibility(可见性)下拉菜单,然后单击可见性。 更多信息请参阅“更改 GitHub Pages 站点的可见性”。 选择站点可见性的下拉菜单

  21. 要查看您已发布的站点,请在“GitHub Pages”下点击您的站点 URL。 已发布站点的 URL

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

:如果网站 未自动发布,请确保有一个拥有管理权限和经验证的电子邮件地址的人已推送到默认发布源。

后续步骤

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

您可以将 Jekyll 主题添加到 GitHub Pages 站点,以自定义站点的外观。更多信息请参阅“使用 Jekyll 添加主题到 GitHub Pages 站点”。

此文档对您有帮助吗?

Privacy policy

帮助我们创建出色的文档!

所有 GitHub 文档都是开源的。看到错误或不清楚的内容了吗?提交拉取请求。

做出贡献

或, 了解如何参与。