从 0 开始配置一个 GitHub Pages 博客
最快的配置方式是 fork 一个别人的仓库,然后在它的基础上进行修改。
TOC
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
命令来初始化网站目录,本文也是这么做的。
-
创建并初始化网站目录
./myblog
:jekyll new myblog
-
打开新建的网站目录:
cd myblog
-
构建网站并试运行:
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
上选择就行,但如果配置不当可能会出现页面格式崩坏。所以最好还是先在本地更换,测试成功后再部署。
-
指定主题(以
hacker
为例)-
修改
_config.yml
中的theme
项:# 注释掉默认主题,再指定主题 # theme minima theme jekyll-theme-hacker
-
添加
jekyll-theme-hacker
到Gemfile
:echo 'gem "jekyll-theme-hacker"' >> Gemfile
-
-
修改头信息
因为
hacker
只包含default
和post
默认布局,而没有home
和page
默认布局,所以你需要修改引用了home
的index.md
和 引用了page
的about.md
的头信息:--- # layout: page layout: default ---
-
修改主页或编写布局
由于
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
目录下所有文章的静态页面。 -
测试
bundle exec jekyll serve
提示:现在的
jekyll
支持热更新,你可以在启动服务后修改博客(不包括配置文件_config.yml
),刷新网页就可以看到修改内容。如果报错按照错误信息操作即可,一切顺利的话,打开 http://localhost:4000 应该会看到以下界面:
-
完善网站
之后你就可以正常地添加文章和修改网站样式,不过在开始之前可以看看
jekyll
的官方教程 Step by Step Tutorial
6. 最佳实践
-
在
_config.yml
中指定文件编码encoding: UTF-8
-
在
_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"
-
在头信息里自定义变量,然后就可以在
Liquid
模板中被调用下面的示例就用到了自定义的
title
变量:<!DOCTYPE HTML> <html> <head> <title>从 0 开始配置一个 GitHub Pages 博客</title> </head> <body> ...
-
使用
post_url
标签链接到其他博文,例如:[Name of Link]({% post_url 2010-07-21-name-of-post %})
-
自定义摘要
Jekyll
会自动取每篇文章从开头到第一次出现excerpt_separator
的地方作为文章的摘要,并将此内容保存到变量post.excerpt
中。
如果你不喜欢自动生成摘要,你可以在文章的YAML
头信息中增加excerpt
来覆盖它。另外,你也可以选择在文章中自定义一个excerpt_separator
:--- excerpt_separator: <!--more--> --- Excerpt <!--more--> Out-of-excerpt
-
使用
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 %}
-
使用草稿
草稿是你还在创作中而暂时不想发布的文章,可以不给草稿设置发布时间。想要开始使用草稿,你需要在网站根目录下创建一个名为
_drafts
的文件夹,并新建你的第一份草稿:|-- _drafts/ | |-- a-draft-post.md
为了预览你拥有草稿的网站,运行带有
--drafts
配置选项的jekyll serve
或者jekyll build
。这两种方法都会将草稿的发布时间设置为草稿的修改时间,作为其发布日期,所以你将看到当前编辑的草稿文章作为最新文章被生成。 -
使用
permalink
自定义页面的URL
,例如:--- permalink: /about/ ---