从 0 开始配置一个 GitHub Pages 博客

最快的配置方式是 fork 一个别人的仓库，然后在它的基础上进行修改。

TOC

• 1. 安装 Jekyll

• 2. 初始化

• 3. 写博客（Blogging）

• 4. 部署到 GitHub

• 5. 更换主题

• 6. 最佳实践

• 参考

1. 安装 Jekyll

Note: 本文使用 Ubuntu 20.04 作为演示环境，你也可以到这里查看其他操作系统的安装教程。

现在有很多搭建博客的框架，比如流行的 Hexo 和商业性的 WordPress。

但是本文选择一种更 old school 的框架，也就是标题中的 Jekyll，这也是 GitHub Pages 默认支持的框架，比较适合喜欢 DIY 的人。

安装 Jekyll 的第一步是安装依赖，因为 Jekyll 是一个用 Ruby 编写的包（在 Ruby 中包被称为 gem），所以我们首先需要安装 Ruby 和一些其它的构建工具。

# 安装 Ruby 和其他的一些依赖
sudo apt-get install ruby-full build-essential zlib1g-dev

如果你不想以 root 用户安装 Ruby 的包，你最好在 Shell 配置文件中指定 Gems 的安装目录（bash 的配置文件是 ~/.bashrc，zsh 的配置文件是 ~/.zshrc）。

在配置文件里加入以下环境变量：

# Install Ruby Gems to ~/gems
export GEM_HOME="$HOME/gems"
export PATH="$HOME/gems/bin:$PATH"

别忘了更新环境变量：

source ~/.bashrc

终于到安装 Jekyll 的时刻了，因为 Jekyll 是一个 RubyGem，所以我们可以用 gem 安装：

gem install jekyll bundler

Note: 我们还安装了另一个 RubyGem，也就是 bundler，它可以保证你每次运行 Jekyll 的环境都是相同的，这也是推荐的做法。

2. 初始化

如果你选择的是 fork 其他人仓库的方式，那么你就可以跳过这一步，但还是推荐你亲手试试从无到有创建一个 Jekyll 网站的过程。

最简单的方法时使用 jekyll 命令来初始化网站目录，本文也是这么做的。

1. 创建并初始化网站目录 ./myblog：

   jekyll new myblog
   

2. 打开新建的网站目录：

   cd myblog
   

3. 构建网站并试运行：

   bundle exec jekyll serve
   

   如果一切顺利的话，通过浏览器打开 http://127.0.0.1:4000 就可以看到 Jekyll 通过默认模板生成的网站了，你可以在这个网站上到处逛逛，看看 Jekyll 都生成了哪些页面，并在之后的学习中尝试修改这些页面，毕竟 Jekyll 是可以完全自定义的。

   

   实际上这条命令会在当前目录下创建一个 _site 目录来存放生成的网站代码，然后在 http://127.0.0.1:4000 上运行，并且会在编辑博客的时候自动更新网站代码。

   Hint: 如果你想要网页也实时刷新，可以为命令加上 --livereload 参数。

   如果你不需要一个运行的网页服务器，可以用 bundle exec jekyll build，这条命令只会生成网站代码而不会运行服务器。

   Note: 如果你选择的是 fork 他人仓库来初始化，这一步可能会遇到“找不到依赖包”的错误，这可以通过 bundle install 来解决，这也是使用 bundler 的好处之一。

3. 写博客（Blogging）

博文默认存放在项目的 _posts 目录下，所以我们要做的就是打开这个目录，然后新建一篇博文：

cd _posts

# 新建一篇博文并写入“Hello Jekyll”
touch 2021-09-26-hello-jekyll.md
echo "Hello Jekyll" > 2021-09-26-hello-jekyll.md

注意这里的文件命名，Jekyll 要求每篇博文的名字必须符合 YEAR-MONTH-DAY-title.MARKUP 的规范，YEAR 必须是一个 4 位的数字，MONTH 和 DAY 则必须是 2 位的数字，MARKUP 就是博文源文件的扩展名。如果不这么命名，这篇博文就不会出现在最后的网页里。

然会我们需要返回项目的根目录，并运行 Jekyll 的网站服务：

cd ..
bundle exec jekyll serve

Jekyll 的哲学之一是“内容为王”，意思就是博客的内容才是个人博客最重要的东西，也就是说现在你已经学会了 Jekyll 中最核心的功能——写博客了，只差最后一步——部署网站了！

4. 部署到 GitHub

---

在部署之前你需要按照提示修改 Gemfile 文件：

# gem "jekyll", "~> 3.9.0"

# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
gem "github-pages", group: :jekyll_plugins

先推送到一个现有的 GitHub 仓库，并且开启 GitHub Pages，选择网站的源目录，然后你的网站应该就能成功部署了。

详细教程请看：Creating a GitHub Pages site with Jekyll

5. 更换主题

---

更换主题其实也十分简单，只需要在 GitHub 上选择就行，但如果配置不当可能会出现页面格式崩坏。所以最好还是先在本地更换，测试成功后再部署。

1. 指定主题（以 hacker 为例）

   1. 修改 _config.yml 中的 theme 项：

      # 注释掉默认主题，再指定主题
      # theme minima
      theme jekyll-theme-hacker
      

   2. 添加 jekyll-theme-hacker 到 Gemfile:

      echo 'gem "jekyll-theme-hacker"' >> Gemfile
      

2. 修改头信息

   因为 hacker 只包含 default 和 post 默认布局，而没有 home 和 page 默认布局，所以你需要修改引用了 home 的 index.md 和 引用了 page 的 about.md 的头信息：

   ---
   # layout: page
   layout: default
   ---
   

3. 修改主页或编写布局

   由于 hacker 提供的布局不会自动生成一个包含所有 post 的主页，所以你需要自己编写布局文件，或重写主页文件 index.html 或 index.md（现在应该还是空的）。

   编写布局文件请参考 Layouts

   编写主页你可以参考 Blogging

   以下给出一个主页文件 index.html 的示例：

   ---
   layout: default
   title: Blog
   ---
   <h1>Latest Posts</h1>
   
   <ul>
   {% for post in site.posts %}
      <li>
      <h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
      {{ post.excerpt }}
      </li>
   {% endfor %}
   </ul>
   

   上述代码使用了 Liquid 模板，会生成一个包括了 _posts 目录下所有文章的静态页面。

4. 测试

   bundle exec jekyll serve
   

   提示：现在的 jekyll 支持热更新，你可以在启动服务后修改博客（不包括配置文件 _config.yml），刷新网页就可以看到修改内容。

   如果报错按照错误信息操作即可，一切顺利的话，打开 http://localhost:4000 应该会看到以下界面：

   

5. 完善网站

   之后你就可以正常地添加文章和修改网站样式，不过在开始之前可以看看 jekyll 的官方教程 Step by Step Tutorial

6. 最佳实践

---

1. 在 _config.yml 中指定文件编码

   encoding: UTF-8
   

2. 在 _config.yml 中设置默认头信息

   defaults:
   -
      scope:
         path: ""    # 一个空的字符串代表项目里的所有文件
         type: "posts"   # 指定类型为 post
      values:
         layout: "my-site"
   -
      scope:
         path: "projects"  # 代表目录 projects/
         type: "pages" # 以前的 `page`， 在 Jekyll 2.2 里。
      values:
         layout: "project" # 覆盖之前的默认布局
         author: "Mr. Hyde"
   

3. 在头信息里自定义变量，然后就可以在 Liquid 模板中被调用

   下面的示例就用到了自定义的 title 变量：

   <!DOCTYPE HTML>
   <html>
      <head>
         <title>从 0 开始配置一个 GitHub Pages 博客</title>
      </head>
      <body>
      ...
   

4. 使用 post_url 标签链接到其他博文，例如：

   [Name of Link]({% post_url 2010-07-21-name-of-post %})
   

5. 自定义摘要

   Jekyll 会自动取每篇文章从开头到第一次出现 excerpt_separator 的地方作为文章的摘要，并将此内容保存到变量 post.excerpt 中。
   如果你不喜欢自动生成摘要，你可以在文章的 YAML 头信息中增加 excerpt 来覆盖它。另外，你也可以选择在文章中自定义一个 excerpt_separator:

   ---
   excerpt_separator: <!--more-->
   ---
   
   Excerpt
   <!--more-->
   Out-of-excerpt
   

6. 使用 Liquid 模板嵌入带行号的高亮代码

   {% highlight ruby linenos %}
   def show
   @widget = Widget(params[:id])
   respond_to do |format|
      format.html # show.html.erb
      format.json { render json: @widget }
   end
   end
   {% endhighlight %}
   

7. 使用草稿

   草稿是你还在创作中而暂时不想发布的文章，可以不给草稿设置发布时间。想要开始使用草稿，你需要在网站根目录下创建一个名为 _drafts 的文件夹，并新建你的第一份草稿：

   |-- _drafts/
   |   |-- a-draft-post.md
   

   为了预览你拥有草稿的网站，运行带有 --drafts 配置选项的 jekyll serve 或者 jekyll build。这两种方法都会将草稿的发布时间设置为草稿的修改时间，作为其发布日期，所以你将看到当前编辑的草稿文章作为最新文章被生成。

8. 使用 permalink 自定义页面的 URL，例如：

   ---
   permalink: /about/
   ---
   

参考

• Jekyll 的常用变量

• Creating a GitHub Pages site with Jekyll

• Ruby 101

• 使用 Jekyll 向 GitHub Pages 站点添加内容

• Step by Step Tutorial

• Error upon bundle exec jekyll 3.8.7 new . for GitHub Pages

• https://jekyllrb.com/docs/liquid/tags

• https://jekyllrb.com/docs/permalinks/