使用 Jekyll 创建 GitHub Pages 网站

先决条件

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

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

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

为您的网站创建存储库

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

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

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

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

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

   

2. 使用所有者下拉菜单选择您希望拥有该存储库的帐户。

   

3. 为您的存储库输入名称和可选描述。如果您正在创建用户或组织网站，您的存储库必须命名为<user>.github.io或<organization>.github.io。如果您的用户或组织名称包含大写字母，您必须将字母小写。有关更多信息，请参阅“关于 GitHub Pages”。

   

4. 选择存储库可见性。有关更多信息，请参阅“关于存储库”。

创建您的网站

在您创建网站之前，您必须在 GitHub 上拥有一个用于您的网站的存储库。如果您没有在现有存储库中创建网站，请参阅“为您的网站创建存储库”。

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
   

   如果您选择从 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
   

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 创建的 .gitignore 文件，并通过添加以下行来忽略 gems 锁定文件

    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，将 BRANCH 替换为您正在处理的分支的名称。

    git push -u origin BRANCH
    

19. 配置您的发布源。有关更多信息，请参阅 "为您的 GitHub Pages 网站配置发布源。"。

20. 在 GitHub 上，导航到您网站的仓库。

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

    

22. 在侧边栏的“代码和自动化”部分，点击 页面。

23. 要查看您的已发布网站，在“GitHub Pages”下，点击 访问网站。

    

    注意：将更改推送到 GitHub 后，您的网站可能需要长达 10 分钟才能发布。如果您在一小时后仍然没有在浏览器中看到 GitHub Pages 网站更改的反映，请参阅“关于 Jekyll 构建错误的 GitHub Pages 网站”。

24. 您的 GitHub Pages 网站使用 GitHub Actions 工作流程构建和部署。有关更多信息，请参阅“查看工作流程运行历史记录”。

    注意：GitHub Actions 对公共仓库免费。对于超出每月免费分钟数配额的私有和内部仓库，将收取使用费。有关更多信息，请参阅“使用限制、计费和管理”。

下一步

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

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