Github pages + Jekyll 搭建技术博客

发表于 | 分类于
通过Github Pages搭建站点的前提是需要有个github账号

初始化Github Pages

  • 创建repository=username.github.io，username必须是github的username，不然后续可能会返回不到这个url

step_1_1

  • 给这个repository创建默认的index.html 
    1
    2
    3
    4
    5
    6
    7
    8
    9
    // clone
git clone https://github.com/listen2code/listen2code.github.io.git
// create index.html
cd listen2code.github.io
echo "Hello World" > index.html
// push
git add --all
git commit -m "Initial commit"
git push -u origin master
  • 访问https://listen2code.github.io/

以上步骤参考Github Pages搭建，站点初步已经搭建好了，接下来就要改造index.html，使其可以展示首页，分类等常见博客页面组件，这里需要使用Github Pages官方推荐Jekyll静态网页生成工具。

Step by Step to Jekyll

环境搭建：由于Jekyll是用Ruby写的，所以先搭建Ruby环境（版本>2.4.0）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 安装 Homebrew
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

# 安装 ruby
brew install ruby

# 将ruby path添加到环境变量中
export PATH=/usr/local/opt/ruby/bin:$PATH

# 重启terminal后，检查ruby安装情况

which ruby
# /usr/local/opt/ruby/bin/ruby

ruby -v
# ruby 2.6.4p104 (2019-08-28 revision 67798) [x86_64-darwin18]

mac系统默认的ruby可能和Homebrew安装的ruby冲突，需要进行以下配置，使默认找到的ruby为Homebrew下载的最新版本。

1
2
3
4
export PATH="/usr/local/opt/ruby/bin:$PATH"
export LDFLAGS="-L/usr/local/opt/ruby/lib"
export CPPFLAGS="-I/usr/local/opt/ruby/include"
export PKG_CONFIG_PATH="/usr/local/opt/ruby/lib/pkgconfig"
  • 安装jekyll：
1
2
3
4
5
6
# 安装jekyll
gem install jekyll bundler

# 任意选择一个目录，例如：/Users/xx/，执行以下命令，会在该目录下生成Gemfile配置文件
bundle init
# Writing new Gemfile to /Users/xx/Gemfile

打开/Users/xx/Gemfile文件，将”gem jekyll”添加在末尾

1
2
3
4
5
6
7
# frozen_string_literal: true

source "https://rubygems.org"
git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }

# 添加在这里
gem "jekyll"

1
2
3
4
5
6
7
8
9
10
# 执行"bundle"，安装相关gem依赖，这里卡住会有点慢
bundle
# 省略...
# Bundle complete! 1 Gemfile dependency, 28 gems now installed.
# Use `bundle info [gemname]` to see where a bundled gem is installed.

# 检查bundle执行结果
bundle info jekyll
#jekyll (4.0.0)
# Summary: A simple, blog aware, static site generator

新建首页

新建个目录/User/xx/root，创建index.html

1
2
3
4
5
6
7
8
9
10
<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Home</title>
  </head>
  <body>
    <h1>Hello World!</h1>
  </body>
</html>

1
2
3
4
5
6
7
8
9
# 进入到root目录
cd /User/xx/root

bundle exec jekyll serve --trace
# ...
# Server address: http://127.0.0.1:4000
# Server running... press ctrl-c to stop.

# 执行"bundle exec"后，会在/User/xx/root/_site目录生成符合w3c标准的index.html文件，通过浏览器访问 http://127.0.0.1:4000，即可以看到显示"Hello World"的页面

Liquid语法

在html头部定义变量my_content，并可以在”{{}}”中使用Liquid表达式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

---
my_content: Hello World!
---

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Home</title>
  </head>
  <body>
    <h1>{{ page.my_content }}</h1>
  </body>
</html>

_layouts目录：用于存放布局模板文件

新建”/User/xx/root/_layouts/default.html”：

1
2
3
4
5
6
7
8
9
10
11
12

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>{{ page.title }}</title>
  </head>
  <body>
    {{ content }}
  </body>
</html>

修改index.html，设置layout=default，相当于将index的文本内容include到default.html的”{{content}}”标签内，可以通过在_layout目录下定义布局模板，供其他页面引用，实现布局样式的统一：

1
2
3
4
5
---
layout: default
title: Home
---
<h1>"Hello World!"</h1>

_includes目录：用于存放可以复用的组件

新建”/User/xx/root/_includes/navigation.html”，设置导航条目的link

1
2
3
4
<nav>
  <a href="/">Home</a>
  <a href="/about.html">About</a>
</nav>

修改default.html，通过include表达式将导航栏添加在布局模板中

1
2
3
4
5
6
7
8
9
10
11
12
13

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <title>{{ page.title }}</title>
  </head>
  <body>
    {% include navigation.html %}
    {{ content }}
  </body>
</html>

_data目录：存放数据

新建”/User/xx/root/_data/navigation.yml”，Jekyll默认将生成可以直接访问的site.data.navigation数据集合

1
2
3
4
- name: Home
  link: /
- name: About
  link: /about.html

修改navigation.html，遍历site.data.navigation生成a标签

1
2
3
4
5
6
7
8
9

<nav>
  {% for item in site.data.navigation %}
    <a href="{{ item.link }}">
      {{ item.name }}
    </a>
  {% endfor %}
</nav>

_posts目录：存放blog文件的目录111

新建”/User/xx/root/_posts/2019-1-1-blog1.html”，Jekyll将会在/User/xx/root/_site/2019/01/01目录下生成blog1.html

1
2
3
4
5
---
layout: post
author: listen
---
this is blog1

新建”/User/xx/root/_layouts/post.html”，专门用于显示blog的布局模板

1
2
3
4
5
6
7
8
9

---
layout: default
---
<h1>{{ page.title }}</h1>
<p>{{ page.date | date_to_string }} - {{ page.author }}</p>

{{ content }}

新建”/User/xx/root/blog_list.html”，用于展示_posts目录下的blog列表

1
2
3
4
5
6
7
8
9
10
11
12
13

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

发布

执行”bundler exec”后自动生成_site目录，将_site目录下的内容拷贝到github的username.github.io目录下即完成发布

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
.
├── _config.yml
├── index.html
├── blog_list.html
├── about.html
├── _data
|   └── navigation.yml
├── _includes
|   ├── navigation.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2019-1-1-blog1.html
├── _site
|   ├── 执行"bundler exec"后自动生成的html文件
|

jekyllthemes快速搭建

可以在jekyllthemes，选择一个现成的jekyllthemes完成快速搭建

  • 选择themes模板NexT，并下载zip
  • 解压后获得jekyll-theme-next-master目录
  • cd jekyll-theme-next-master，执行”bundle”下载相关gem依赖
  • 根据使用教程修改jekyll-theme-next-master/_config.yml完成页面基础设置，如：页面组件布局，主题，头像，分类目录等
  • 将blog文件放置在_posts目录下
  • cd jekyll-theme-next-master，执行”bundle exec jekyll serve –trace”，生成_site目录
  • 将_site目录下的内容拷贝到listen2code.github.io的localpath，并同步到github
  • 访问https://listen2code.github.io