关于本站

前言

  正如大家所知，Jekyll 是一款高可定制的、非常流行的静态博客生成工具。围绕着 Jekyll 也衍生出了很多优秀的 Jekyll 主题， 本站采用了 H2O 、 jekyll-theme-H2O-ac。

  在此，非常感谢廖柯宇及其他小伙伴对于 H2O-ac 主题的基础主题 H2O 的代码开发和开放共享。

新特性

PDF在线预览

[XXX.pdf](/assets/js/web/viewer.html?file=%2Fassets/pdf/XXX.pdf)

提示框

  通过引入 lazee/premonition 库新增五种提示框：笔记、提示、警告、错误、引用，完全兼容原生 Markdown 语法，并对样式进行了主题适应。以下为五种提示框的实际效果。

代码高亮优化

  本人使用 H2O 主题的时候代码高亮功能还是沿用的 Jekyll 自带的，后来 H2O 主题也开始采用了 Prism.js。不过由于使用的是 OKAIDIA 高亮主题，所以有些段落中的格式化字段显示上有些问题。这里，仍然采用默认主题，并且扩增到 Prism.js 支持的所有编程语言类型。效果可以从前一句的 OKAIDIA 字段和下面即将出现的代码片段看出。

@font-face {
  font-family: 'Merriweather';
  src: local('Merriweather'), url(https://fonts.gstatic.com/...) format('woff2');
}

  更换 Prism 库加载方式，采用按需自动加载代码类型，尽可能减少因 Prism 造成的阻塞。修复了某些样式问题。增加显示行数支持、官方主题选择支持。如下所示可以进行设置，具体主题风格样式可以访问 Prism 官网 了解更多。

  除官方代码库中默认代码主题外，新增扩展代码主题支持，比如常用的 One Light 等等。具体主题风格样式可以查看 PrismJS/prism-themes 了解更多。

# Prism
prism:
  theme: tomorrow
  line_numbers: true

代码复制

  由于主题设置有复制自动添加版权保护文字，导致复制代码或无法直接使用。但是如果直接去掉版权保护又不大合适，于是新增代码复制功能。当使用如下所示代码片段右上角的复制按钮时，代码会被复制到粘贴板，且不包含版权保护文字，可以放心直接使用。

  调整复制按钮位置，自动识别代码块的代码类型并显示。

<!-- Target -->
<input id="foo" value="https://github.com/zenorocha/clipboard.js.git">

<!-- Trigger -->
<button class="btn" data-clipboard-target="#foo">
    <img src="assets/clippy.svg" alt="Copy to clipboard">
</button>

文章置顶功能

  鉴于现有的 Jekyll 文章置顶库有点年久失修，决定徒手实现了一下文章置顶功能。具体文章列表页和归档页置顶效果如下所示：

分页依赖升级

  由于原有的 jekyll-paginate 库已停止更新，所以升级到目前更新、维护活跃的 jekyll-paginate-v2 库。原有的分页配置自 v1.1.7 版本后无法使用，请更换为如下类似设置：

# _config.yml 旧配置
paginate: 10
paginate_path: 'blog/page:num'

# _config.yml 新配置
pagination:
  enabled: true
  per_page: 10
  permalink: 'page:num/'

  另外，blog/index.html 的头部信息中应该加上如下启用分页的配置。否则，jekyll-paginate-v2 不会主动工作。

pagination: 
  enabled: true

封面图片作者及链接

......
cover: ''
cover_author: ''
cover_author_link: ''
......

  非文章的页面中也可以像上面那样声明相关的封面作者及链接，效果如下所示：

字数统计及阅读时间估计

  字数统计及阅读时间估计这个小功能其实以前在用 WordPress 的时候比较常见。虽然说统计和估计的结果不一定完全准确，但是还是起到了一定的辅助阅读的作用。效果可以查看本页标题下的基本信息区域。

时间本地化与最近更新时间

  为了支持来自不同时区的读者直接可以看到文章发布对应的本地时间，现已利用 dayjs 新增时间本地化功能。并利用 Github API 查询页面的最近一次 commit 更新时间作为文章最近更新时间。效果如下图所示。

  如需使用最近更新时间功能，务必在 _config.yml 文件中添加以下配置项：

# Github
github:
  enabled: true
  owner: github_username
  repository: github_project_name

  如未正确进行以上配置，默认会将最近更新时间与发布时间保持一致。

版权显式声明

  之前的版本只会在页面底部的信息栏中显示一个 CC 4.0 的小图标，不是很醒目。根据调研其他静态网站主题，发现一般都会在文章的末尾自动生成一个比较醒目的版权声明。另外，在版权声明中也将根据最近更新时间来判断内容是否可能过时。如果最近更新时间距离当前时间大于 365 天，则会显示具体日期并提醒有内容过时的可能。效果如下所示。

文章侧边索引导航

  在一些基于 Bootstrap 前端框架的 Jekyll 主题中，这个功能比较常见。由于本主题未使用 Bootstrap 前端框架，所以添加起来稍微有些麻烦，现已增加此功能。在浏览器窗口超过 1050 px 的情况下，在文章页面可以正常看到右侧的文章侧边索引导航。当窗口滑动时，侧边索引导航也会跟着滑动。在浏览器窗口不足 1050 px 的情况下，侧边索引导航自动隐藏。在 _config.yml 配置文件中，可以通过设置 toc: false 来全局禁用此功能。

  在原来的基础上增加了跟随左侧内容滑动高亮。当左侧内容向上或向下滑动时，右侧索引导航将会使对应的对应一级标题高亮。

  为文章的移动端页面添加了索引导航按钮。鉴于单页面的内容有限及侧边位置空间有限，暂未对单页面进行支持。

支持 Waline 评论系统

  目前已支持基于 Valine 衍生的简洁、安全的评论系统 Waline。可以根据官方提供的 快速上手 进行配置，以下为 _config.yml 中需要配置的内容：

# _config.yml

comments:
  waline: true
  waline_url: https://xxxxxx.vercel.app

支持 PWA

  全面支持 PWA，访问速度得到较大提升。移动端访问可以像原生 APP 那样使用。如果访问过全站一遍之后，则可以完全离线使用。如下所示，可以配置 PWA 的主题色和短名称。

# PWA
pwa:
  color: '#81BBFF'
  short_name: 'lisz'

支持 Mermaid

  不少同学可能会有在文章中放置流程图的需求，为了满足这一需求，现添加了 Mermaid 来支持像写代码一样画图。

  为了兼容 Markdown 语法，这里采用了自定义的代码类型。当代码类型为 mermaid 时，PrismJS 会自动以代码的形式美化展示；当代码类型为 mermaid2 时，页面会自动使用 Mermaid 画成图展示出来，如下所示。

  考虑到页面宽度有限，Mermaid 所画出的甘特图等其他比较大一点的图不太好看，也增加了放大重绘的功能。如下所示，点击图的右上角的按钮即可全屏查看大图。

    graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

    gantt
      title A Gantt Diagram
      dateFormat x
      axisFormat %L
      section Section
      A task           :a1, 0, 30ms
      Another task     :after a1, 20ms
      section Another
      Another another task      :b1, 20, 12ms
      Another another another task     :after b1, 24ms

    gantt
    dateFormat  YYYY-MM-DD
    title       Adding GANTT diagram functionality to mermaid
    excludes    weekends
    %% (`excludes` accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".)

    section A section
    Completed task            :done,    des1, 2014-01-06,2014-01-08
    Active task               :active,  des2, 2014-01-09, 3d
    Future task               :         des3, after des2, 5d
    Future task2              :         des4, after des3, 5d

    section Critical tasks
    Completed task in the critical line :crit, done, 2014-01-06,24h
    Implement parser and jison          :crit, done, after des1, 2d
    Create tests for parser             :crit, active, 3d
    Future task in critical line        :crit, 5d
    Create tests for renderer           :2d
    Add to mermaid                      :1d
    Functionality added                 :milestone, 2014-01-25, 0d

    section Documentation
    Describe gantt syntax               :active, a1, after des1, 3d
    Add gantt diagram to demo page      :after a1  , 20h
    Add another diagram to demo page    :doc1, after a1  , 48h

    section Last section
    Describe gantt syntax               :after doc1, 3d
    Add gantt diagram to demo page      :20h
    Add another diagram to demo page    :48h

配置项

  配置项中新增了友情链接和备案号功能，可以直接在 _config.yml 文件的对应配置项下设置即可，如下所示。友情链接主要是方便跟其他博主交换友链，备案号主要是为了方便部署在国内需备案的 vps 或虚拟主机上。此处，二者都可以置空。

  新增全站一键灰度化功能、时间格式配置。在国家公祭日等需要灰度化以示哀悼的时候可以将灰度化配置设置为 true，平常使用默认配置 false。时间格式这里一共提供了 3 种：第一种中英文站点使用皆宜，第二种适用于英文站点，第三种适用于中文站点。默认时间格式为第一种。

  新增 不蒜子 统计方式，可以显示全站访问次数、全站访问用户数、文章页面阅读量。如下设置可以开启。

  新增 umami 统计方式，需要自行先搭建 umami 然后接入。接入配置只需要如下所示配置跟踪 id 和 JS 脚本地址。

# Links 友情链接
links:
  'Mr Li': 'https://lisz.me'

# Beian 备案号
beian: '沪ICP备xxxxxxxx号'

# Gray 灰度化
gray: true

# Time format 时间格式 
# 0 -- 2022-04-29    1 -- 29 Apr 2022   2 -- 2022年4月29日
formats:
  time: 0 

# Busuanzi Analytics
busuanzi: true

# Umami Analytics
umami:
  status: true
  id: xxxxxxxxxxxxx
  js: https://umami.example.com/umami.js

前端自动构建工作流优化

  H2O 主题中使用了 Gulp + Node-Sass Sass 的方案来自动化前端构建工作流。不得不说，这个方案还是很不错的，只是随着 Gulp 和 Node-Sass Sass 版本的更新，对 NodeJS 环境及其他依赖库都有一些要求。这里，H2O-ac 主题在 package.json 文件中将所有库都更新到目前最新，对应版本列表如下所示。另外，为了减少一些第三方 CSS 样式的请求数，利用自动构建工作流将固定的第三方 CSS 样式文件合并并压缩为 plugins.min.css 文件。app.min.css 仍为多个自编写 CSS 样式文件的合并压缩。