github + jekyll 搭建博客

自从使用 markdown 写文档后，感觉已经离不开它了。工作这么久，遗憾没有条理化地将知识落地，做了大量重复劳动。幸运 github 提供了一个很好的源码管理和博客平台，我们可以通过 git + github + jekyll + vscode 等工具管理自己的博客内容。

目前国内网络对 github 平台不是很友好，如有条件，可以部署博客到云主机上。

[我的博客] [框架] 来自 Gaohaoyang。

1. 目的
2. 搭建流程
3. 域名
- 3.1. 域名重定向
- 3.2. CDN 加速
4. 系统部署
5. 优化
6. 启动
7. markdown 编辑器
- 7.1. 插件
- 7.2. 图片
8. ECS 云服务部署
- 8.1. 安装服务
- 8.2. nginx 配置
9. 参考

1. 目的

对知识进行条理化管理。有几点要求：

终端简洁，无广告，无推荐。
支持 markdown。
支持文章分类管理。
支持文章题目搜索。

2. 搭建流程

github 上搭建博客，并不复杂。jekyll + github 搭建详细文档，网络上很多，可以参考这个，细节问题，还是需要花点时间，简单记录一下流程：

会 git 的基本使用方法。
注册一个 github 账号。
在 github 上建立自己的博客项目 xxx.github.io。
拷贝别人的 yyy.github.io 文件放在自己的目录下。
别人的 yyy.github.io 项目有别人的信息，需要整理成自己的。
本地查看博客预览。（请参考这个文档的搭建流程）
本地预览正常，git 提交文件到 github。
浏览器打开链接 xxx.github.io。

git 提交后，页面内容刷新不是实时的，大概需要等 1 分钟左右。

3. 域名

域名不是必须的，它的好处就不用多说了。

阿里云购买域名。
阿里云域名绑定云主机 ip。

以前没有备案过的，域名需要实名认证，备案，这需要等，可以先用 ip。

3.1. 域名重定向

参考：Github Pages(io) + 域名重定向 (手把手教你搭建个人网站)

阿里云域名重定向，将购买的域名重定向到你的 xxx.github.io 域名。
在你的 xxx.github.io 目录下添加 CNAME 文件，写入你的域名 xxx.com，提交文件到 github。
域名要升级为 https，参考 http 升级 https。

3.2. CDN 加速

详细参考：利用CDN加速你的Github Pages

添加 CDN 加速域名。

添加 DNS 解析 CDN 加速的相关记录。

申请免费 https 证书。

CDN 加速，设置 https，选择已申请的免费 https。

CDN 配置防盗链。

4. 系统部署

如果你只用 xxx.github.io，博客也能正常使用，但是预览不是很方便，还有 github 有时候网络很慢，这时候需要部署本地的，或者将它部署在云服务。

4.1. Linux

4.1.1. 安装 ruby

centos7，yum 默认安装 ruby 版本太低，需要升级到 2.3 以上。

# 安装开发工具
yum groupinstall "Development tools"
# 清理安装过的 ruby 文件
yum erase ruby ruby-libs ruby-mode ruby-rdoc ruby-irb ruby-ri ruby-docs
# 安装依赖
yum -y install zlib-devel curl-devel openssl-devel httpd-devel apr-devel apr-util-devel mysql-devel

下载源码包安装：

cd /home/soft
wget https://cache.ruby-lang.org/pub/ruby/2.6/ruby-2.6.5.tar.gz
tar zxf ruby-2.6.5.tar.gz
cd ruby-2.6.5
./configure
make && make install
# 查看 ruby 运行版本。
ruby -v

4.1.2. 拉取代码

cd /home/other/
git clone https://github.com/xxx/xxx.github.io.git

我的 blog 图片现在越来越多了，代码拉取可能会有点慢，直接从 github 下载压缩包可能更快一点。

4.1.3. 运行 jekyll 服务

cd xxx.github.io
gem install jekyll bundler
bundle install
# jekyll serve -wIt
bundle exec jekyll serve

4.2. MacOS

MacOS 与 Linux 安装大同小异，不同 macOS 系统版本安装遇到的问题可能不一样。

4.2.1. 安装流程

# 查看版本号，确认是否被升级。
sudo ruby -v

# 卸载 ruby
brew uninstall ruby

# 重新安装 ruby，或者安装指定版本的 ruby。
brew install ruby
#brew install ruby@3.0

# 配置默认使用指定版本 ruby
###########################
# vim ~/.zshrc
export PATH="/usr/local/opt/ruby@3.0/bin:$PATH"
export LDFLAGS="-L/usr/local/opt/ruby@3.0/lib"
export CPPFLAGS="-I/usr/local/opt/ruby@3.0/include"
###########################

# 安装 jekyll
sudo gem install jekyll bundler

# 进入项目目录
cd xxx.github.io

# 安装指定的 gem 包。
sudo bundle install

# 余下环节，拉取代码，运行 jekyll 服务，参考 Linux 的步骤。

【注意】 本地系统更新以后，ruby 或者其它配置可能已经更新了，要重新根据当前系统相关软件版本信息，更新项目的 Gemfile，然后将项目运行起来，如有问题，通过查看日志，定位问题。也可以通过 jekyll 新建一个项目，生成新的 Gemfile，然后拷贝到旧的项目运行。

4.3. windows

win10/win11

cd xxx.github.io。
删除 Gemfile 和 Gemfile.lock。
安装 ruby - 3.1.x。
gem install jekyll bundler。
bundle init。
然后在 Gemfile 文件添加下面内容：

# frozen_string_literal: true

source "https://rubygems.org"

gem "jekyll", "~> 4.0.0"
group :jekyll_plugins do
    gem "jekyll-feed", "~> 0.6"
    gem "jekyll-paginate"
end

gem "kramdown", ">= 2.3.1"
gem "wdm", "~> 0.1.1", :install_if => Gem.win_platform?
gem "webrick", "~> 1.7"

bundle install。
bundle exec jekyll serve

5. 优化

5.1. 代码块

原来框架的代码块代码自动换行，字体太大，还屏蔽了滚动条滚动功能。在手机上看，感觉挺别扭的，可以修改文件 _sass/_syntax-highlighting.scss 相关选项设置。

pre {
    margin: 12px 0;
    padding: 8px 12px;
    overflow-x: auto;      // 滚动条滚动功能
    word-wrap: break-word;      /* IE 5.5-7 */
    // white-space: pre-wrap;      /* current browsers */
    white-space: none;     // 代码自动换行  /* current browsers */
    > code {
        margin: 0;
        padding: 0;
        font-size: 12px;   // 代码块字体大小
        color: #d1d1c9;
        border: none;
        background-color: #272822;
        line-height: 1em;
    }
}

代码主题，可以在 _sass/_syntax-highlighting.scss 的 .highlight 中，调整自己喜欢的颜色。也可以引用第三方插件 highlight.min.js

.highlight {
    border-radius: 3px;

    background: #272822;
    .hll { background-color: #272822; }
    .c { color: #6a9955 } /* Comment */
    ...
}

5.2. 搜索文章题目功能

原框架没有搜索功能，可以将这个博客的搜索组件添加进来。有些代码没扣得好，搜索页面还有点问题，凑合着用吧。

双击键盘 ctrl 键，或者点击页面搜索图标，调出搜索窗口。

5.3. 其它功能

后面陆续增加了一些功能：作者版权信息，分享，打赏，评论（gitalk）。

有些功能感觉没啥用屏蔽了，有需要的同学再重新打开吧。

新增功能

5.4. 提交博客文章

写博客文章，经常操作的只有 images 和 _posts 目录，将 git 的几个命令 pull，add，commit，push 整合在一起方便操作。

脚本 commit.sh：

#!/bin/sh
# -------------------------------------------------------------------------------
# project  blog
# file:    commit.sh
# brief    整合多个 git 命令，方便提交文章。
# author:  wenfh2020
# date:    2020-02-18
# note:    ./commit.sh msg1 msg2
# -------------------------------------------------------------------------------

cd `dirname $0`
work_path=`pwd`
cd $work_path

if [ $# -lt 1 ]; then
    echo 'pls input commit message'
    exit 1
fi

_files='images _posts commit.sh refresh.sh _config.yml README.md _includes'
git pull && git add $_files && git commit -m "$(echo "$@")" && git push -u origin master && git status

6. 启动

用脚本 refresh.sh 启动 jekyll 服务。

更新页面信息一般不需要重启，更新系统配置 _config.yml 文件就需要重启服务。

#!/bin/sh
# -------------------------------------------------------------------------------
# project  refresh
# file:    refresh.sh
# brief    rebuild blog to run.
# author:  wenfh2020
# date:    2020-02-18
# note:    nohup ./refresh.sh >> /tmp/blog_log.txt 2>&1 &
# -------------------------------------------------------------------------------

cd `dirname $0`
work_path=`pwd`
cd $work_path

# find and kill
_pids=`ps -ef | grep 'jekyll serve' | grep -v grep | awk '{print $2}'`
for p in $_pids
do
    echo "kill pid=$p"
    kill -9 $p
done

# 有时候不能实时刷新，需要删除 _site 目录，重新启动。
[ -d _site ] && rm -r _site
# jekyll serve -wIt
bundle exec jekyll serve

后台运行 jekyll 服务。contab 后台定时刷新，可以将时间设置短一点。

# crontab -e
* */12 * * * nohup /home/other/xxx.github.io/refresh.sh >> /tmp/blog_log.txt 2>&1 &

jekyll 服务的其它功能配置，可以参考帮助。

jekyll serve -h

7. markdown 编辑器

markdown 编辑器可以用 vscode，有不少插件支持。

7.1. 插件

插件	描述
Markdown All in Once	文档编写基本插件。
Markdown Preview Enhanced	预览。
markdownlint	语法检查。
Markdown TOC	自动生成目录。
PicGo	可以关联图床。
Paste Image	在编辑器贴图。

Paste Image 插件主要配置项：

配置项	数据
Base Path	${projectRoot}
Insert Pattern	${imageSyntaxPrefix}/${imageFilePath}${imageSyntaxSuffix}
Path	${projectRoot}/images

7.2. 图片

在博客目录下创建 images 文件夹，用于存放文章用到的图片。

markdown 插入图片格式如下：

![](/images/123.png){: data-action=”zoom”}

8. ECS 云服务部署

github 国内的网络访问不是很稳定，特别是图片加载。可以将博客部署到云端，云主机从 github 上拉取代码，更新博客内容。

博客更新流程：

本地 vscode 编辑 markdown 文档。
本地网页预览博客。
上传代码到 github。
云主机上用 git pull 拉取代码。（可以用 crontab 定时执行脚本）
刷新域名对应博客。

8.1. 安装服务

参考上面 系统部署 章节。

8.2. nginx 配置

添加域名到新的 nginx 配置文件。
http 升级 https，证书是免费的。（证书到期，免费延长使用时间）

mkdir -p /etc/nginx/vhost
cd /etc/nginx/vhost
vim blog.conf

# 注意 nginx.conf 中默认的 80 端口处理.
# 如果没有使用，可以注释掉 nginx.conf 的 80 端口的 server。

server {
    listen 80;
    server_name  xxx.com www.xxx.com;
    # http 转 https
    return 301   https://$host$request_uri;
}

server {
    listen       443 ssl;
    server_name  xxx.com www.xxx.com;
    ssl_certificate /usr/local/nginx/ssl/blog/3515736_xxx.com.pem;
    ssl_certificate_key /usr/local/nginx/ssl/blog/3515736_xxx.com.key;
    ssl_session_timeout 5m;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers AESGCM:ALL:!DH:!EXPORT:!RC4:+HIGH:!MEDIUM:!LOW:!aNULL:!eNULL;
    ssl_prefer_server_ciphers on;

    root /home/other/xxx.github.io;
    # 反向代理
    location / {
        proxy_pass http://localhost:4000;
    }

    # 防止盗链
    location ~ .*\.(gif|jpg|jpeg|png|bmp|swf)$ {
        root /home/other/xxx.github.io;
        valid_referers none blocked server_names  ~\.google\. ~\.baidu\. ~\.bing\.;
        if ($invalid_referer) {
            return 403;
        }

        expires    30d;
        access_log off;
    }
}

添加新域名文件路径到主配置文件。

vim /etc/nginx/nginx.conf

http {
    ...
    # 添加新域名文件
    include /etc/nginx/vhost/*.conf;
}

刷新 nginx 配置

nginx -s reload