GitHub 中文社区
论坛
排行榜
趋势
返回训练营

GitHub Pages

使用 GitHub Pages 创建一个基于您的GitHub仓库的网站或博客

Welcome

使用 GitHub Pages，您可以托管个人博客、项目文档、您的简历、作品集或您想要展示的任何静态资源内容。 您的 GitHub 仓库可以轻松成为自己的网站。 在本课程中，我们将向您展示如何使用 GitHub Pages 设置您自己的网站或博客。

  • 目标人群：新手，学生，项目维护者，小型企业
  • 课程目标：构建一个 GitHub Pages 站点
  • 你将构建：我们将使用 Jekyll (一个静态网站生成工具) 构建一个博客网站
  • 前置条件：如果您不熟悉分支、提交、拉取请求，请先学习我们的GitHub快速入门课程
  • 学习时长：小于一个小时

通过本课程，您将

  1. 启用 GitHub Pages
  2. 配置您的站点
  3. 自定义网站首页
  4. 创建一篇博客文章
  5. 合并您的拉取请求

如何开始

start-course

  1. 右键点击上方 Start course 按钮

  2. 在新页面中根据系统提示新建一个仓库。

    • 仓库名称、描述这些字段系统已经帮我们自动填充好了，您可以按需修改。
    • 建议使用选择公共仓库，因为私有仓库 GitHub Action有免费额度限制
    • 最后点击 Create repository 按钮

  3. 仓库创建完毕后，等待大约 20 秒（等待Action执行），然后刷新页面。注意是刷新您仓库的页面，不是本课程的页面。如果页面没有变化，请继续等待。

步骤1：启用 GitHub Pages

欢迎来到 GitHub Pages 、Jekyll 🎉!

第一步，您需要在新仓库上启用GitHub Pages。启用后，GitHub 会自动获取 main 分支的内容并用于发布网站。

⌨️ 动手

  1. 点击您仓库的 Settings 菜单

  2. 进入设置后，点击 Code and automation 下的 Pages

  3. 请确保 Source 下拉框选择 "Deploy from a branch"，Branch 选择 main

  4. 点击 Save 保存

  5. 等待大约20秒，然后刷新页面。GitHub Actions 将自动更新到下一步。

    启用 GitHub Pages 会创建仓库的部署。 在等待部署期间，GitHub Actions 可能需要长达一分钟的时间才能响应。 这一步比较慢，请您耐心等待，后续步骤大约是20秒。 注意：在Pages设置页面顶部，会出现您网站的链接地址，复制链接或点击 "Visit site" 按钮可查看您的 GitHub Pages 站点。

步骤2：配置您的网站

恭喜，您已开启了GitHub Pages！🎉

我们将在我为您创建的一个分支my-pages中工作，以使该网站看起来很棒。 ❇️

Jekyll 使用名为 _config.yml 的文件来保存站点配置、如主题、网站名称、等设置。

我们需要使用博客主题，这里我们选择 "minima"。

动手练习：开始配置您的站点

  1. 切换到my-pages分支，点击_config.yml文件

  2. 右上角有个编辑按钮，打开文件编辑器

  3. 为了使用minima主题，我们在_config.yml文件里添加下面的内容

    theme: minima

  4. （可选）您还可以添加其他配置变量，例如站名title:, 作者author:、站点描述description:

  5. 提交修改

  6. （可选）创建一个拉取请求以便查看您在本课程中将进行的所有更改。 单击Pull Requests tab，单击New pull request，设置base: main和compare:my-pages

  7. 等待大约20秒，然后刷新页面。GitHub Actions 将自动更新到下一步。

步骤3：自定义你的网站首页

干的漂亮，您已设置好了网站主题✨

想要自定义首页，您可以修改 index.md 或者 README.md 文件，向其添加内容。GitHub Pages 会首先查找是否有 index.md 文件。 我们的仓库里已经有一个 index.md 文件，因此我们可以修改它。

⌨️ 动手练习：创建您的首页

  1. 切换到my-pages分支，点击index.md文件
  2. 右上角有个编辑按钮，打开文件编辑器
  3. 在编辑框内输入你想要在首页上展示的内容，注意使用Markdown格式
  4. （可选）您还可以修改 title: 或暂时不管，我们将在下一步中讨论
  5. 提交my-pages分支中的修改
  6. 等待大约20秒，然后刷新页面。GitHub Actions 将自动更新到下一步。

步骤4：发布一篇文章

您的首页看起来很棒！🤠

GitHub Pages 使用 Jekyll 工具来生成网站。在 Jekyll 中，博客需要遵守特定的文件命名格式和frontmatter。文件必须以 _posts/YYYY-MM-DD-title.md 方式命名， frontmatter中必须包括title和date。

什么是frontmatter？ Jekyll 文件使用的语法称为 YAML frontmatter，它位于文件开头，示例如下：

---
title: "Welcome to my blog"
date: 2019-01-20
---

更多关于front matter配置说明请参考 Jekyll frontmatter 文档

⌨️ 动手练习：创建一篇博客文章

  1. 切换到 my-pages 分支

  2. 点击 Add file 点击 Create new file 创建文件

  3. 文件取名为 _posts/YYYY-MM-DD-title.md

  4. 将 YYYY-MM-DD 替换为今天的日期，同时可以修改title

    如果您确实要编辑标题，请确保单词之间有连字符。 如果您的博客文章日期不遵循正确的日期约定，您将收到错误消息，并且您的网站将无法构建。 有关详细信息，请参阅“排查 GitHub Pages 站点的 Jekyll 构建错误”。

  5. 将下面的内容放于文件顶部

    ---
title: "YOUR-TITLE"
date: YYYY-MM-DD
---

  6. 将 YOUR-TITLE 替换为你真实的文章标题

  7. 将 YYYY-MM-DD 替换为今天的日期，例如 2023-09-04

  8. 快速编写一段文章草稿，后面可以随时对其修改

  9. 提交修改

  10. 等待大约20秒，然后刷新页面。GitHub Actions 将自动更新到下一步。

步骤5：合并您的拉取请求

干的漂亮，朋友 ❤️！大家很快就能阅读您的博客！

您现在可以合并您的拉取请求！

动手

  1. 将my-pages分支的修改合并到main。如果您已经在步骤2中创建了Pull Request，那么现在只需打开那个PR，然后点击Merge pull request完成合并。 如果您之前没有创建，现在可以按照步骤2 中的说明进行操作。

  2. (可选) 删除my-pages分支

  3. 等待大约20秒，然后刷新页面。GitHub Actions 将自动更新到下一步。

完成

恭喜您完成了本课！

课程回顾：

  1. 首先您开启了 GitHub Pages
  2. 在config文件中指定网站主题
  3. 学习Jekyll的文件命名规范
  4. 使用Jekyll创建了您的第一篇文章