1+1=10

记记笔记，放松一下...

GitHub Pages 随手小记

点开之前用GitHub Pages搭建的项目页面qtlsx.debao.me，看到上次更新还是在9年前。长时间没写博客，有点不清楚从哪儿开始了。或许先把GH Pages捡起来看看，毕竟10年来发生了很多变化。

GitHub Pages 是 GitHub 提供的一项免费服务，它允许用户创建和托管个人博客、项目文档、演示页面等静态网站。无需外部服务器或复杂的配置，就快速创建并发布自己的博客。

GitHub Pages的官网地址： https://pages.github.com/

站点类别

GH Pages站点有两种(三种)：

  • 用户级，每个用户一个：仓库名必须为 <username>.github.io
  • 组织级，每个组织一个：仓库名必须为 <orgname>.github.io
  • 项目级，每个项目一个：仓库名不限制，访问地址为 <userororgname>.github.io/<projectname>

用户级和组织级其实是一样的，属于一类，都需要放置到一个特定名字的仓库中；而项目级不同，它名字随意， 但是它必须属于一个用户或一个组织。一个用户可以有数量不限的项目级站点。

注意点

私有与免费

对于GitHub的免费用户，只能在公有仓库中开启 GitHub Pages。

如果要在私有仓库中开启 GitHub Pages，需要升级到收费用户。

gh-pages分支不是必须

在2016年之前，项目站点内容需要推送到gh-pages分支才能生效。这个限制早已不存在。

现在可以在master或其他分支的根目录或docs目录下，只需要在仓库的settings中做一下配置即可。

参考：

  • https://github.blog/2016-08-17-simpler-github-pages-publishing/
  • https://stackoverflow.com/questions/35978862/github-pages-why-do-i-need-a-gh-pages

https 支持

对于使用自定义域名的公有仓库，只需要在Settings中勾选Enforce HTTPS即可。

自定义域名

如果自己有域名的话，配置子域名来指向GH Pages站点比较简单

  • 仓库中添加一个名为CNAME文件（必须这个名字），里面包含自定义的域名（只能包含一个域名，且占据一行）
  • 配置DNS，使其指向 <userororgname>.github.io（不管是项目级别站点还是用户级站点）

参考：

  • https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages

Jekyll

Github Pages内置了Jekyll（音标 /'dʒiːk əl/）这一静态站点生成器的支持。通过_config.yml可以对Jekyll进行配置。

Jekyll是采用Ruby编写的，博客形态的静态站点生成器。它有一个模版目录，其中包含原始文本格式的文档， 通过一个转换器（如 Markdown）和的 Liquid 渲染器转化成一个完整的可发布的静态网站，以便发布在任何服务器上。

如何要禁用Jekyll，可以在根目录下创建一个名为.nojekyll的空文件。

参考：

  • https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/about-github-pages-and-jekyll
  • https://jekyllrb.com/docs/github-pages/

最简的支持Jekyll的GH Pages站点

本地不安装 Jekyll 这套Ruby的东西，做一个最简单的支持Jekyll的GitHub Pages站点。

创建一个代码仓库，按如下设置，并放置一个index.md文件。站点完成！

仓库设置

Settings => Pages => Buid and deployment

Source: 选择 Depoly from a branch

Branch：选择 main root

仓库文件

  • 需要存在一个 index.md 文件，文件头部需要有三个中横线构成的头部
1
2
3
---
title: Home
---

很多人说如果没有index.md的话，会使用README.md文件，个人试过不行，不知道是否姿势不对造成的。

  • https://github.com/dbzhang800/jekyll-test

GitHub Actions

GH Pages除了支持传统的 Depoly from a branch 方式，还支持GitHub Actions方式。

借助 Github Actions，不仅可以使用Jekyll，还可以使用其他站点生成器。如果不想使用GitHub pages，也可以使用Actions将生成的站点推送到其他免费主机，比如 Kinsta或 azure 等。