Post

使用Jekyll + GitHub Pages搭建个人博客

本文将介绍如何使用Jekyll搭建个人博客,并部署在GitHub Pages上。

1.简介

Jekyll是一个强大的静态网站生成器,可以将Markdown、HTML、Liquid模板等文件转换为静态网站。Jekyll支持模板引擎、主题、插件、集成GitHub Pages等特性,可以帮助用户快速搭建和发布静态网站。

官方网站:https://jekyllrb.com/

2.安装

Jekyll支持大多数操作系统,依赖如下:

下面介绍在Windows系统上的安装步骤,其他操作系统见官方文档安装指引:https://jekyllrb.com/docs/installation/

2.1 安装Ruby

在Windows上安装Ruby最简单的方式是RubyInstaller。

下载地址:https://rubyinstaller.org/downloads/,选择 Ruby+Devkit 版本,使用默认选项安装即可。

在安装向导最后一步勾选“运行ridk install”:

ridk install

在弹出的命令行窗口中选择 “MSYS2 and MINGW development tool chain”:

MSYS2 installation choice

检查是否安装成功:

1
2
ruby -v
gem -v

2.2 安装Jekyll

打开一个新的CMD窗口,执行以下命令安装Jekyll和Bundler:

1
gem install jekyll bundler

检查是否安装成功:

1
jekyll -v

3.Jekyll基础

3.1 Jekyll教程

在正式开始搭建个人博客之前,建议先按照Jekyll官方教程Step by Step Tutorial搭建一个Demo网站,了解Liquid模板(变量、标签、过滤器)、前页(front matter)、布局(layout)等基本概念,并学会使用jekyll命令。

Demo网站:https://zzy979.github.io/jekyll-tutorial/

Demo site

3.2 Jekyll目录结构

Jekyll项目的典型目录结构如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
mysite/
  _data/
    foo.yml
  _includes/
    foo.html
  _layouts/
    default.html
    post.html
  _posts/
    2018-08-20-bananas.md
    2018-08-21-apples.md
  _sass/
    main.scss
  _site/
  assets/
    css/
    images/
    js/
  _config.yml
  index.html
  Gemfile

作为博客作者,主要关注以下文件/目录即可(其他目录用于存放主题样式文件):

文件/目录描述
_config.yml配置文件
_posts文章内容,文件命名格式为YYYY-MM-DD-TITLE.EXTENSION
_siteJekyll生成的网站文件
assets/images文章中的图片文件
index.html网站主页

详见官方文档Directory Structure

3.3 主题

主题(theme)提供了网站页面的布局和样式,详见官方文档Themes

可以在 http://jekyllthemes.org/ 选择自己喜欢的主题并在线预览。我选择的主题是Chirpy,该主题提供了分类(category)、标签(tag)、目录、语法高亮、数学公式、搜索文章、评论系统等特性,能够满足博客网站的绝大部分需求。

4.搭建个人博客

下面正式开始搭建个人博客网站。参考:Chirpy - Getting Started

4.1 创建网站

打开chirpy-starter仓库,点击按钮 “Use this template” → “Create a new repository”。

create-repository-step1

将新仓库命名为<username>.github.io,其中<username>是你的GitHub用户名,如果包含大写字母需要转换为小写。

create-repository-step2

注:如果不需要自定义主题样式,则推荐使用这种方式,因为容易升级,并且能隔离无关文件,使你能够专注于文章内容写作。

4.2 安装依赖

使用git clone将新创建的仓库克隆到本地,并在项目根目录下执行

1
bundle

4.3 配置

根据需要更新_config.yml中的变量,例如urlavatartimezonelang等。

4.4 启动本地服务器

要在本地预览网站内容,执行

1
bundle exec jekyll serve

在浏览器访问 http://127.0.0.1:4000/

4.5 部署

GitHub Pages是一个通过GitHub托管和发布网页的服务,官方文档:https://docs.github.com/en/pages。本文使用GitHub Pages部署个人博客网站。

每个GitHub用户可以创建一个用户级网站,仓库名为<username>.github.io,发布地址为 https://<username>.github.io。GitHub Pages支持自定义域名,参考文档About custom domains and GitHub Pages

在部署之前,检查_config.yml中的url是否正确配置为上述发布地址(或者自定义域名)。

注意:一般不需要配置baseurl。如果配置了,则文章中必须使用relative_url过滤器生成正确的URL,否则会导致404错误。参考Jekyll’s site.url and baseurl

之后在GitHub上打开仓库设置,点击左侧导航栏 “Pages”,在 “Build and deployment” - “Source” 下拉列表选择 “GitHub Actions”。

github-pages-deployment-source

提交本地修改并推送至远程仓库,将会触发Actions工作流。在仓库的Actions标签页将会看到 “Build and Deploy” 工作流正在运行。构建成功后,即可通过配置的URL访问自己的博客网站。

https://zzy979.github.io

personal-blog-site

4.6 评论系统

Jekyll生成的博客网站是静态的,没有后端和数据库,因此本身无法实现评论功能。然而,可以使用disqusutterancesgiscus等评论系统来实现评论功能。

本文使用giscus,它是利用GitHub Discussions实现的评论系统,并且是开源、免费的。开启评论系统的步骤如下。

(1)安装giscus app

(2)在仓库设置页面 “Features” 一节中勾选 “Discussions”,开启仓库的GitHub Discussions功能。

enable-github-discussions

(3)在仓库的Discussions标签页,点击 “Categories” 旁边的编辑按钮,自定义用于博客评论的类别名称(例如 “Comments”)。

edit-discussions-categories

(4)打开 https://giscus.app/,在页面上填写以下配置:

  • Repository: <username>/<username>.github.io
  • Page - Discussions Mapping:保持默认值 “Discussion title contains page pathname” 即可(URL为https://<username>.github.io/posts/<title>的文章将映射到标题为/posts/<title>的Discussion,即使用URL的pathname部分作为Discussion标题)
  • Discussion Category:选择上一步创建的类别名称(例如 “Comments”)

之后找到 “Enable giscus” 一节,将自动生成的配置填写到_config.yml中comments.giscus的对应选项。

giscus-config

1
2
3
4
5
6
7
8
comments:
  active: giscus
  giscus:
    repo: ZZy979/zzy979.github.io
    repo_id: R_kgDOKOkhRA
    category: Comments
    category_id: DIC_kwDOKOkhRM4CZCpN
    mapping: pathname

(5)重启Jekyll服务器,在文章底部将会看到评论区,使用GitHub账号登录即可发表评论。

comment-system-enabled

4.7 写文章

至此,博客网站已经搭建完成,可以开始文章写作了。

要写一篇新的文章,在_posts目录下创建一个文件,命名格式为YYYY-MM-DD-TITLE.md(例如2023-09-03-hello-world.md),TITLE部分将作为文章的URL。

详细配置和语法参考Chirpy文档:

Front Matter

你需要在文章顶部填写Front Matter信息:

1
2
3
4
5
6
---
title: TITLE
date: YYYY-MM-DD HH:MM:SS +/-TTTT
categories: [TOP_CATEGORIE, SUB_CATEGORIE]
tags: [TAG]
---

其中,title将展示为文章标题(不必与文件名的TITLE部分相同),date将展示为文章创建时间(时区写+0800)。

之后是正文内容。

分类和标签

categories是文章的分类,支持至多两级分类。tags是文章的标签,可以有任意多个。例如:

1
2
3
4
---
categories: [Animal, Insect]
tags: [bee]
---

目录

默认情况下,目录将会自动生成并展示在文章右侧。如果想全局关闭,则将_config.yml中的toc变量设置为false。如果想对一篇特定的文章关闭,则在Front Matter中添加:

1
2
3
---
toc: false
---

注意:Chirpy生成的目录只显示二级标题(##)和三级标题(###),一级标题(#)不会显示在目录中。参考issue #491

This post is licensed under CC BY 4.0 by the author.