Post

Jekyll 和 GitHub Pages 的使用教程

Posted Updated
By Chenguang Wan
5 min read
Jekyll 和 GitHub Pages 的使用教程

Jekyll Chrispy 主题和 GitHub Pages 使用教程

本文主要参考以下文章

1
2
3
4
5
6
7
8
9
10

# only use for fast experience
sudo apt-get install ruby-full build-essential zlib1g-dev
## add to bashrc the Gems
echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc 
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc 
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc 
source ~/.bashrc

## install jekyll and bundler
gem install jekyll bundler

Fork Chrispy theme

  1. Fork chrispy theme 重命名为 .github.io

  2. 拉到本地 git clone git@github.com:<username>/<username>.github.io.git

  3. 执行初始化

    1
2
3

    cd <username>.github.io
bash tools/init.sh # 这一步非常重要
bundle install

  4. 打开 Jekyll server

    1
2
3
4
5
6
7

    bundle exec jekyll s
# 或者使用
bash tools/run.sh # 添加了livereload功能
# 或者使用
bundle exec jekyll s --livereload
# 不建议使用，因为render很奇怪
jekyll s

  5. push 到 GitHub

    1
2

    # push 之前先执行
bash tools/test.sh  # 本地构建检查比Github action 要快，而且方便

常见问题处理

Q: 仅出现 — layout: home # Index page — jekyll chrispy

A: 大概率是没有执行 bash tools/init.sh

复制已有远程仓到其他设备

配置环境

  1. 安装 rbenv
    1
2
3
4

     sudo apt install rbenv
 # add the following statements in .bashrc
 export PATH="$HOME/.rbenv/bin:$PATH"
 eval "$(rbenv init -)"
  2. 用 rbenv 重新安装 ruby，建议版本号高于 3.2
    1
2
3

     # list all available envs can be installed 
 rbenv install -l
 rbenv install <ruby_version>

  3. 安装 node，参考 安装教程

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

     # recommend to use fnm
 # Download and install fnm:
 curl -o- https://fnm.vercel.app/install | bash

 # Download and install Node.js:
 fnm install 22

 # Verify the Node.js version:
 node -v # Should print "v22.14.0".

 # Verify npm version:
 npm -v # Should print "10.9.2".

  4. 安装 Jekyll 等

    1
2
3
4
5
6
7
8
9

     rbenv versions # should be something like 3.2.2

 # if not
 rbenv global <version_gt_3.2>
 rbenv rehash
 ruby -v # should be ruby 3.4.2

 ## install jekyll and bundler
 gem install jekyll bundler

  5. git clone git@github.com:<username>/<username>.github.io.git

  6. cd <the folder>; bundle install

  7. 测试结果: tools/test.sh

Tricks

markdown 语法参考

GitHub markdown 基本语法教程

在 _config.yml 中添加新的 collections

用以让 Jekyll 可以编译除 _post 之外的位置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

collections:
  tabs:
    output: true
    sort_by: order
  owns:
    output: true
    permalink: /posts/owns/:title/  # 这个地方是文件编译的位置
  
defaults:
  - scope:
      path: "" # An empty string here means all files in the project
      type: posts
    values:
      layout: post
      comments: true # Enable comments in posts.
      toc: true # Display TOC column in posts.
      # DO NOT modify the following parameter unless you are confident enough
      # to update the code of all other post links in this project.
      permalink: /posts/:title/
  - scope:
      path: "_owns"
      type: owns
    values:  
      layout: post

修改 pages-deploy.yml 用以忽略一些测试

  • 修改 .github/workflows/pages-deploy.yml 文件

    1
2
3
4
5
6
7
8

     # 主要修改了 test部分 增加了 \-\-no-enforce-https \ 用以不启用https检查
      - name: Test site
        run: |
          bundle exec htmlproofer _site \
            \-\-no-enforce-https \ 
            \-\-disable-external \
            \-\-ignore-urls "/^http:\/\/127.0.0.1/,/^http:\/\/0.0.0.0/,/^http:\/\/localhost/"

  • 参考 链接，寻找 htmlproofer command line 用法

  • 因为修改了 .github/workflows/pages-deploy.yml 文件，故也要修改 tools/test.sh 用以保持一致

    1
2
3
4
5

      # --no-enforce-https 为新加部分
  bundle exec htmlproofer "$SITE_DIR" \
    --no-enforce-https \
    --disable-external \
    --ignore-urls "/^http:\/\/127.0.0.1/,/^http:\/\/0.0.0.0/,/^http:\/\/localhost/"

实现指定 update 和自动 update 两种 update 时间方法

按照如下方式修改 _layouts/post.html 文件

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

      <!-- manual update date -->
      {% if page.updated and page.updated != page.date %}
        <span>
          {{ site.data.locales[lang].post.updated }}
          {% include datetime.html date=page.updated tooltip=true lang=lang %}
        </span>
      <!-- lastmod date -->
      {% elsif page.last_modified_at and page.last_modified_at != page.date %}
        <span>
          {{ site.data.locales[lang].post.updated }}
          {% include datetime.html date=page.last_modified_at tooltip=true lang=lang %}
        </span>
      {% endif %}

实现自动 update 时间在非 _post 文件夹工作的方法

按照如下方式修改 _plugins/posts-lastmod-hook.rb 脚本

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

Jekyll::Hooks.register [:documents,:posts], :post_init do |post|
  # Skip drafts and static files
  next unless post.respond_to?(:collection)
  # for the root of _post be triged twice.
  next if post.data['lastmod_checked']

  commit_num = `git rev-list --count HEAD "#{ post.path }"`

  if commit_num.to_i > 1
    lastmod_date = `git log -1 --pretty="%ad" --date=iso "#{ post.path }"`.strip
    unless lastmod_date.empty?
      post.data['lastmod_checked'] = true
      post.data['last_modified_at'] = lastmod_date
    end
  end
end

快速部署

1
2
3
4

git clone git@github.com:chgwan/chgwan.github.io.git
# 需要先安装Gems, ruby, node 等, 安装方法如下安装方法
cd chgwan.github.io
bundle install

安装方法

其他注意事项

  1. 当 list 和 code block 在一起使用时，render 会可能会出现问题，建议参考本文件的 code block in list 进行部署。主要原则就是在 code block 和 list 之间加上 return key
Tutorial
Tutorial Jekyll
This post is licensed under CC BY 4.0 by the author.

Trending Tags

Tutorial Note Jekyll Tex