使用 Highlight.js 优化代码块高亮效果

    Hexo

对博客的代码块(code block)部分的显示一直不是很满意,拖延到今天算起来一共是两年多了。这次总算下定决心搞一把。虽然当前是满意了,不过过程遇到各种坑让我觉得有必要写一篇博客来帮助未来的自己和其他有缘的过客。


为什么是 Highlight.js

Hexo 本身就自带高亮功能,只不过不完美,比如 Scheme 这个我常用的语言它就没有高亮效果。话虽如此,这个自带的高亮功能在我所用的主题里也比市场上的其他插件(例如 Hexo-Prism-Pluginhexo-filter-highlightPrettify 这三个坑货)要好用得多。这里说的好用,主要体现在最终渲染出来的排版效果上的美观、设置上的便捷,且不会引入过多 Markdown 和 Latex 之间语法的冲突。

经过一番调研,最终我放弃安装 Plugin(插件)版本的 Highlight.js( hexo-filter-highlight 就是一个基于 Highlight.js 开发的 Plugin 。这些 Plugin 虽然安装设置方便,其模块化属性也方便管理,但如果效果不好,不如不用),直接选择使用原版的 Highlight.js 。你可以在官方 Demo 页面查看它各个语言在各个风格(Style)下的显示效果。


实现

由于 cps.ninja 使用的是 pln 主题,所以下面的步骤将以该主题为例来设置 Highlight.js

步骤一:

前往 Highlight.js 的官方下载页面,在 Custom package 的部分勾选你希望获得高亮支持的语言(想一步到位就全选),勾选完毕后点击 Download 按钮下载,得到 highlight.zip 压缩包;

步骤二:

解压刚刚的 highlight.zip 压缩包,得到 highlight.pack.js 文件和 styles文件夹(该文件夹中包含了各种显示风格的 CSS 文件)。接着,将 highlight.pack.js 文件移动到 themes/pln/source/js/ 目录下,而 styles 文件夹(包括里面的所有 CSS 文件)则移动到 themes/pln/source/css/highlight 目录下;

步骤三:

修改根目录下 _config.yml 文件中 highlight 部分的设置(主要目的是关闭它,其他设置只是顺便说明一下):

highlight:
  enable: false          ## 关闭 hexo 自带的 highlight 
  line_number: false
  # auto_detect: false   ## 这里要注释掉是因为 hexo 自带的 highlight 的 auto_detect 这个属性有 bug ,且之后要被官方抛弃  
  tab_replace: 2

步骤四:

修改 themes/pln/layout/_partial/after_footer.ejs ,增加了以下两行(目的是调用第二步里我们下载的 highlight.pack.js 文件):

<script src="/js/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

修改 themes/pln/layout/_partial/head.ejs ,增加了以下一行(通过调用指定的 CSS 文件选择相应的高亮风格,下面的例子里选择的风格是 Vs 2015):

<link rel="stylesheet" href="/css/highlight/styles/vs2015.css">

其他微调

  • 修改文件 themes/pln/source/css/main.scss,在末尾(为了覆盖前面的设置,所以加在末尾)添加 CSS 设置,white-spaceword-wrap 属性会分别让 Chrome 和 Safari 浏览器支持代码块(code block)左右滑动显示超出内容(overflow):

    pre code {
      white-space: pre;  /* this code line alone can make code block to slide in Chrome */
      word-wrap: normal; /* add this line to make code block to slide in Safari */
    }
    
  • 修改 themes/pln/source/css/highlight.scss 文件里 .code-block 类的 border-color 属性为 #2d2d2d ,使得代码块的边框颜色与背景一致;

    .code-block {
      // ...
      border-color: #2d2d2d;
      // ... 
    }
    

总结

完成上文提到的所有操作之后,使用下面代码让高亮设置生效:

## 生成压缩版的 css(让 pln 主题的相关设置生效)
$ pwd
~/Documents/blog  ## 确认当前目录,因为下面 sass 命令要输入相关路径
$ sass --style compressed themes/pln/source/css/main.scss:themes/pln/source/css/m.min.css  

## 清空缓存,并重新生成文件(让 _config.yml 里的设置生效)
$ hexo clean
$ hexo g

一些心得:

  • 写文章的过程中,有时候会遇到 Markdown 和 Tex 语法冲突或者奇怪显示的情况,不要慌,只需要调整一下写法就能实现想要的效果。实在不行,还可以在 Chrome 的开发者模式下调节 html ,设定出想要的效果后直接复制 html 代码,然后粘贴在 .md 文件里;

  • 按照以上方式挂载 Highlight.js 之后(此时,Tex 语法也已通过这篇介绍配置支持), Markdown 语法中在使用 ``` 标记代码块(code block)时,其间不能有连续两个空白的行,只能有一个

  • 不能紧贴着 Markdown 的 list 标记内容写,之间要有一行空格。之前的「紧贴」是为了实现把代码块(code block)归属于某 list 的 bullet 的那种缩进效果。现在请直接使用 tab 来缩进;


资料

添加 Hightlight.js 参考了:

修复代码显示 Bug 的过程参考了:


打赏