Github Pages and Jekyll安装与使用

简介

github pages
- 可以托管静态资源(HTML、pictures、javascript等)的免费公共空间
- 仓库总大小不能超过1G
- 每个月有100G的流量限额
- 每小时只能生成十次以内
- 三种建立pages的方式
  - 建立一个名为<username>.github.io的仓库，将站点文件全部放在这个仓库的master分支
  - 放在项目的gh-pages分支（访问链接为https://<username>.github.io/<projectname>/）
  - 还有一种可以放在项目的doc或root 文件夹中，具体设置方式看这里
  - 建议用<username>.github.io建个人网站、项目的文档什么的采用后面两种方式
Jekyll
- 一个静态资源生成器
- github pages 御用
- 不用这个工具，单纯手写HTML等也是可以建立起GitHub Pages站点的，比如google style guide。
- 当然也可以在自己的VPS上用这个工具生成静态网站

安装

依赖
- Ruby
- RubyGems
- gcc, make
安装(以Debian为例)

sudo apt install ruby ruby-dev build-essential
# Gem是ruby的包管理工具，安装ruby会默认安装（类似于python的pip）
# bundler是rails的管理工具
gem install bundler jekyll --user-install
export PATH=~/.local/share/gem/ruby/2.7.0/bin:$PATH

创建本地最简单站点

# 设置bundle可以使用普通用户安装
cd ~/
bundle config set --local path 'vendor/bundle'
# 建立空的网站目录并进入
mkdir myblog
cd myblog
# 在./myblog目录创建一个全新的Jekyll网站
# 默认生成的文件可以查看Jekyll的官方文档
jekyll new .
# 构建网站并启动一个本地服务器
bundle exec jekyll serve -H 0.0.0.0
# 在浏览器中打开http://localhost:4000

利用他人主题创建github站点

此处创建站点都以<username>.github.io这种方式作为示例，其他两种方式无非就是静态文件所放置的分支或者位置不一样，文件都是一样的。

创建站点

在github上创建一个<username>.github.io的仓库（username如果有大写字母要改成小写）
将这个仓库clone到本地：git clone git@github.com:EvanYu/evanyu.github.io.git
安装主题Jekyll-Paper

# 下载主题（这里以Jekyll-Paper为例，其他类似）
wget https://github.com/ghosind/Jekyll-Paper/archive/refs/tags/v1.3.2.zip
unzip v1.3.2.zip
# 安装主题
cd evanyu.github.io
cp -rf ../Jekyll-Paper-1.3.2/* ./

基本设置

github的Jekyll设置（参照这里编辑Gemfile）
- 注释掉gem "jekyll"开头的行
- 添加gem "github-pages", "~> 219", group: :jekyll_plugins
编辑 .gitignore文件为如下：

_site/
.sass-cache/
.jekyll-cache/
.jekyll-metadata
Gemfile.lock
.DS_Store
vendor/

基本主题设置
- 删除asserts/images目录下的默认图片
- 替换自己的favicon.ico并删除CHANGELOG文件
- 编辑_config.yml文件定制自己的网站
- 编辑_data/menus.yml和_data/lang.yml定制菜单，菜单中的项目就是对应的pages目录下的页面
- 删除_post下的默认文章，并编写自己的文章
写完文章后的本地测试
- 按照本文中的指引安装jekyll和bundle
- cd ~/并bundle config set --local path 'vendor/bundle'
- 进入网站根目录并执行bundle install（如果网站根目录已经是有vendor文件夹的情况可不用执行）
- 构建网站：bundle exec jekyll serve -H 0.0.0.0
- 访问http://localhost:4000

主题修改

所有超链接划过效果修改（修改_sass/reset.scss文件的部分如下）

a {
  text-decoration: none;
  color: #000;
}

a:hover {
  text-decoration: underline;
  color: #F00;
}

文章中超链接颜色的修改（在_sass/post.scss文件中添加）

/* Change hyper link color to blue in post */
.post-content a {
  text-decoration: none;
  color: #2a7ae2;
}

.post-content a:hover {
  text-decoration: underline;
  color: #F00;
}

在文章中添加目录
- 在_includes文件夹中添加如下toc.html
- 在_layerouts/post.html文件中的{{ content }}之前添加{% include toc.html html=content %}
- 此方法为参照这里的第三种方案
为文章添加序号（在_sass/post.scss文件中添加如下样式）

/* Add numbers to title */
.post-content h2:before{
    content:counter(h2counter) ' ';
}
.post-content h2{
    counter-increment: h2counter;
    counter-reset: h3counter;
}

.post-content h3:before{
    content:counter(h2counter) '.' counter(h3counter)' ';
}
.post-content h3{
    counter-increment: h3counter;
    counter-reset: h4counter;
}

.post-content h4:before{
    content:counter(h2counter) '.' counter(h3counter) '.' counter(h4counter)' ';
}
.post-content h4{
    counter-increment: h4counter;
    counter-reset: h5counter;
}

将标题增加链接（修改文件_includes/header.html的site.title行为如下，即增加一个超链接）

<span class="header-info-name"><a href="/">{{ site.title }}</a></span>

注意事项

markdown 中的行内公式也需要使用双美元符号包围$$行内公式$$

文章目录

简介

安装

创建本地最简单站点

利用他人主题创建github站点

创建站点

基本设置

主题修改

注意事项