本文记录了我如何成功搭建个人 GitHub 网站的经验。

注意： 网上已经有各种各样的详细教程，所以这里仅关注一些关键点。阅读过程中，你可能需要频繁打开其它网站。

背景

在一路艰难摸索的过程中，我发现，初学者若想把一切都优雅地安排好，会遇到许多背景知识方面的门槛。那么，让我们开始吧。

GitHub Pages

GitHub Pages 为所有用户提供免费的个人网站与项目网站。

它的优点有：

  • 完全免费

  • 容易管理

它的缺点有：

  • 只能托管静态内容

  • 博客无法被百度收录

  • 空间不能超过 1G

  • 每月流量不能超过 100G

  • 每小时更新不能超过 10 次

但它是免费的！

按照以下步骤即可启用这项功能。

  1. 获得一个名为“*.github.io”的仓库。仓库内容就是网站的源文件。
  2. 在“Repository - Setting - Pages”中启用这项功能。
  3. 每当仓库更新时，网站“*.github.io”都会自动生成。上传一份 README，然后到“*.github.io”查看它。

请注意：

  • 页面构建需要时间，通常会在 1 分钟内完成。

  • GitHub 上看不到生成后的页面文件。

  • GitHub Pages 既支持 Jekyll，也支持纯 HTML 文档。“Repository - Setting - Pages”中的主题正是 Jekyll 主题。

得到网站之后，下一步就是丰富它的内容。在 GitHub Pages 上，我们通常使用 Jekyll。

Jekyll

Jekyll 提供无需数据库的静态网站与博客生成器。大多数时候，我们通过 Markdown 文件更新 Jekyll 网站。

安装说明：https://jekyllrb.com/docs/installation/

Jekyll 是一个 Ruby“包”，所以要先安装 Ruby。

Ruby

Ruby 是一种面向对象的动态语言。就我们的用途而言，只需安装 Ruby+Devkit。

RubyGems

RubyGems 是 Ruby 的包管理器。它提供分发 Ruby 程序和库的标准格式，也提供管理软件包安装的工具。Ruby 的软件包称为“gem”。

Jekyll 是一个 Ruby gem。

Buddle

Buddle（或 Bundler）通过跟踪并安装项目所需的确切 gem 及其版本，为 Ruby 项目提供一致的环境。

在我们的流程中，有时需要使用 buddle exec。

Jekyll 主题

Jekyll Theme 会指定插件，并将资源、布局、include 和样式表打包，使你的网站内容可以覆盖它们。Jekyll 主题是一个 Gem。具体而言，其中包含这些资源：

  • assets

  • _layouts

  • _includes

  • _sass

以上是我从网上找到的内容。我的猜测是，它的能力不止这些，但我还没有弄清其中的机制。

我的实践

有了以上信息，实际上我们有多种方式可以构建 GitHub Page：

  1. 使用 Jekyll 构建，主题与站点分离
  2. 使用 Jekyll 构建，主题与站点集成
  3. 在本地构建，只上传站点文件

截至当时，我的博客采用方案 2，而方案 1 是最终目标。

主题

Chirpy 是我当时使用的主题，它非常接近我心目中的完美形态。应用主题有三种方式：

  1. 在“_config.yml”中远程导入：remote_theme: cotes2020/jekyll-theme-chirpy
  2. Fork 该项目，然后在“_config.yml”中远程导入这个副本
  3. 复制全部内容，将主题与站点集成，并在“_config.yml”中禁用外部主题

我选择了方案 3，因为 Chirpy 与 Github-Pages Gem 之间存在代码兼容性问题，使用外部主题会不稳定。

Chirpy 也提供了一份教程。

调试

只要 GitHub Page 构建过程中出现 BUG，你就会收到一封电子邮件。

常见构建失败

The page build failed for the master branch with the following error:

Page build failed. For more information, see https://docs.github.com/github/working-with-github-pages/troubleshooting-jekyll-build-errors-for-github-pages-sites#troubleshooting-build-errors.

For information on troubleshooting Jekyll see:

https://docs.github.com/articles/troubleshooting-jekyll-builds

If you have any questions you can submit a request at https://support.github.com/contact?tags=dotcom-pages&repo_id=406411513&page_build_id=279574162

这条消息不会把确切的问题反馈给我们。要处理这种情况，应依靠本地环境，因为可以在控制台中看到 BUG 的反馈。

但要注意，GitHub Page 的构建依赖一组特定的 Gem。其列表见 https://pages.github.com/versions.json。在本地测试时，Gem 版本差异可能导致不同的结果。若要同步，只需在“Gemfile”中引入 Gem：gem 'github-pages'，然后在控制台执行 buddle exec jekyll serve。

_config.yml 失败

The page build failed for the master branch with the following error:

You have an error on line 2 of your _config.yml file. For more information, see https://docs.github.com/github/working-with-github-pages/troubleshooting-jekyll-build-errors-for-github-pages-sites#config-file-error.

For information on troubleshooting Jekyll see:

https://docs.github.com/articles/troubleshooting-jekyll-builds

If you have any questions you can submit a request at https://support.github.com/contact?tags=dotcom-pages&repo_id=406061228&page_build_id=279331936

这类消息会指出 BUG 所在的位置。若要了解更多，只需在本地测试。

结果

而这个网站就是最终成果。

参考资料