Hexo技巧与经验之升级(一)

tips
, ,

0x00.工欲善其事,必先利其器

markdown语法虽好,可是毕竟新的东西或者极简的语法也必然有不顺手的一面. 比如有些语法上手比较奇怪, 特别是流程图/公式, hexo解析语法其实挺严格, 半天发现少了一个空格可能会欲哭无泪. 所以,新手需要一个nice的编辑器来优雅的写文.

郑重推荐: Typora (详细特性可自行查看,秒杀其它md编辑器)

btw:写此文的时间是16年10月6号,如果以后有更好的或者软件开始收费了—麻烦留言告知我修改.

19/10/13更新: .至今还没发现比typora更好的md编辑器. 而且除了字数过多导致的性能问题, 其它越来越强大

在此对有些博主长时间一年两年不更新的blog表示吐槽,hexo跟markdown流行时间不长,很多人刚开始接触只能大量参考前人的blog,但是很多根本就已经完全过时甚至是错误了,死链了也没人管一下,还**口口相传.**后面沿用的可能就被坑的不浅

0x01. Hexo插件的卸载安装管理

把玩hexo有一段时间之后就会发现很多东西自己更加想diy,优化或者调整一下.那么有时候各种坑爹教程中教的并不好用的插件下载安装之后会非常影响速度,还会使hexo的容错率大幅降低,简直不能忍.

特别比如 hexo-qiniu-sync 这种.请神容易送神难,自己找了很久才找到hexo的插件卸载命令(其实应该自己根据node的npm模式推断的,蠢)

1
2
$ npm uninstall moduleName --save
//然后最好看看是不是卸载成功了.

0x02. Hexo常见问题

1.本地无法预览启动

这个问题多半跟上面装了一些不靠谱的插件,然后搞鼓了一下配置文件源码,就崩了~

1
2
3
4
5
#那么本来我一般本地预览附自动打开常用
$ hexo s -o  

#常见问题可以先清理一下
$ hexo clean && hexo g

2.hexo的git问题

常见的各种github无绿点,以及更新失败的错误. 详见我的git排错文章

3.hexo -g的时候Template render error

主要是nunjucks.js的报错, 报错信息如下:

1
2
3
Template render error: (unknown path)
  Error: expected end of comment, got end of file
    at Object._prettifyError (E:\OneDrive\Hexo\node_modules\nunjucks\src\lib.js:36:11)

这个问题你直接排查基本是没救了….但是好在hexo的错误一般都不会是第一个出现, 通过查找官方issue 的信息, 然后根据你判断hexo -g 中断的地方, 基本是说明你文章里出现了无法解析的字符组合{ # .

你可以通过grep -rl "{ #" (两个字符中间没有空格, 因为我只要不输入空格这篇文章就会报错了…)

0x03. 真 · 技巧

更新于: 2018/06/16

首先说一下真是很不好意思…因为两年前一次更换SSD导致的hexo血案.导致整个blog的资料都丢了,其中hexo相关的各种技巧和折腾至少有上万字… 所以后面重建blog后这部份恢复就累觉不爱懒得做了. 直到两年后的一次偶然记忆碎片拾取.. 就继续更新一下这个坑了~

1.博客&文章内的快速链接(跳转)

  • 第一个博客内文章链接比较简单,但是存在一个特殊符号的坑 (本质是访问服务器端文件,而index.html可以省略)

    Q: 特殊符号那每次这么去转义肯定是非常蛋疼的,那我就是想用[] , () 这类符号作为标题末尾怎么办呢?

    A: **我发现有个好办法就是 :**第一次创建保存文件名先不带括号. 比如tile.md .然后保存之后你再修改yaml中的titile: tmame(一) .这样文件名不会受到特殊符号影响(URL),你文章显示渲染的时候标题也有(一).

  • 第二个文章内章节跳转本质应该是用了HTML的# 标记. 很隐蔽…也有点小坑.但是都是用习惯了就非常有用的. (不管是几级标题,都只用一个#即可.)

1
2
3
4
5
6
7
8
9
10
//博客文章跳转
[博客内普通文章跳转](../2018-05-25-Git-flow与常见问题)  //可以成功解析

[特殊符号文章](../小明学习小记(一)) //不能成功解析,因为')'会被识别为末尾. 自己试试就知道
//')'对应转义 
[特殊符号文章](../小明学习小记(一 ) )
//转义为这个样子..才能解析..虽然在typora内可能会显示有点小问题.(其他特殊符号如果冲突同理)

//单篇文章内章节跳转
[我是第二章](#0x02.Hexo常见问题)

2.Hexo的copyright信息

修改themes\themeName\layout\partial\foot.xx ,剩下就自行修改了. 周围的文件一般也能控制不少其他属性,注意慎重修改.

3.Hexo内代码高亮的问题(重点)

这个问题, 比较隐蔽… 但是其实比较棘手, 很多时候你测试的语言是最常用的那几种, 你并不会发现高亮是一个问题, 但是当你在不同主题切换 然后写了比较多的文章的时候. 你就会发现相比Typora这多的惊人的代码高亮支持 (以及自定义的代码高亮) ,然后很多在你blog上都不能正常渲染, 看起来很难受.

那么 . 从根本上了解一下hexo主题代码高亮的原理吧:

首先, hexo默认使用highlight.js 作为代码高亮的插件, 它最新支持的语言列表参考. 你可以在这里(Hexo\node_modules\highlight.js\lib\languages)找到它所有的js源码 . 这有助于你根本上确定许多问题, 而hexo自带的启用高亮 & 行号在根目录下的配置文件就有设置. (注意不是主题配置文件)

其次, 很多主题之所以出现代码高亮支持很少(比如就几种语言) , 或者是完全不支持的情况, 多由以下两种情况导致:

  1. 主题作者在渲染文章的时候使用了自己单独写的高亮逻辑 / 或是就没使用代码高亮, 从而导致默认的highlight.js 失效,
  2. 主题作者自己选择的高亮渲染css覆盖了和highlight.js 设置的渲染. 或者是冲突了自己没发现.

如果你是觉得代码的高亮不够完全, 比如你选择bash ,发现很多Linux常用命令/软件都没有高亮, 可以手动去修改上面的js源码 , 并且你也可以确定哪些缩写能触发高亮, 而哪些不能. 也有助你了解它的运行本质. 比如下面是shell.js 实现, 你就知道其实它本质用的bash.js的高亮..

1
2
3
4
5
6
7
8
9
10
11
12
13
14
module.exports = function(hljs) {
  return {
    aliases: ['console'],
    contains: [
      {
        className: 'meta',
        begin: '^\\s{0,3}[\\w\\d\\[\\]()@-]*[>%$#]',
        starts: {
          end: '$', subLanguage: 'bash' //唔...所以一般Linux高亮建议写bash而不是shell.
        }
      },
    ]
  }
};

但是, 如果你是遇到”在同一个页面, 同样的语言, 部分代码可以高亮, 部分不可以“ , 甚至是同一个代码块, 部分可以高亮, 部分不可以… 这就是比较蛋疼的地方了. 需要分情况来讨论排除

解决方案:

1.排除法
2.升级/加工highlight.js

hexo自带的highlight.js 版本可能是9.11 , 这应该是2017年的版本, 2018最新的版本已经到9.13 了, 比如sql的高亮里不支持注释#的高亮, 但是你不知道使用了, 就可能会导致所有高亮全部失效… 而且改原本的markdown文档是几乎不可能的, 所以只有两个选择:

  • 官方更新 (推荐ncu方式)

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    npm view highlight.js  #查看当前node能查到的最新版本.如果有9.13.x那就直接更新
    #首先建议更新npm到最新版本 (可选) npm -v : 6.x.x
    npm install npm@latest -g


    #更新highlight.js
    npm update highlight.js
    #你发现白光一闪,就结束了,咦. 什么情况,溯源到package.json文件.你会发现..
    #"spec": ">=9.4.0 <10.0.0". NPM只会更新9.4~10.0范围内的版本,想到指定版本
    npm update highlight.js@9.13.1  #发现还是白光一闪没了..什么情况

    #通过ncu插件的方式来快捷更新/check (推荐)
    npm install -g npm-check-updates
    ncu #查看可更新包
    #要注意下面的命令会更新到最新版本,可能有很多bug,慎重选择最新版本.
    ncu -u #更新packag.json文件 (当前目录)
    npm install --save #更新

    #然后到highlight.js文件所在的位置, 然后注意指定package.json (不指定默认取当前目录)
    ncu -u --packageFile package.json
    Using path\Hexo\node_modules\highlight.js\package.json
     del          ^2.0.2  →   ^3.0.0
     jsdom        ^9.2.1  →  ^13.0.0
     mocha        ^2.0.1  →   ^5.2.0
     should       ^9.0.2  →  ^13.2.3
     tiny-worker  ^1.1.1  →   ^2.1.2
    Upgraded package.json 
    #insatll之后如果提示有风险可以npm audit fix处理一下,不要--force.以免出现问题


    #全局更新. global,取决于各个模块的package.json
    npm update -g (可选)
    #新版有个修复安全漏洞的命令,推荐
    npm audit fix

  • 自己手动把# 写到SQL的高亮逻辑里 ,这是最实用的办法, 但是建议还是先更新一下highlight.js的版本, 因为优化了不少解析逻辑, 等于省去了你自己去一个个调优的不少地方.

比如我还比较喜欢的几个主题, 多少有这种问题.

0x04. hexo的升级

其实在上面的highlight.js 的升级里我就已经说了最推荐的方式, 并进行了升级, 但是这里为了方便参考, 还是单独得说一下步骤:

  1. 如果node版本 < 9, 强烈建议先升级到最新的node-stable版本, Win下直接覆盖安装也很简单. (这样npm的版本也是最新的一般, 避免后面各种冲突)

  2. 检查node -v , npm -v (应该是至少6.12.0), 如果npm没有更新, 则手动更新 npm install npm@latest -g

  3. 进入核心的升级步骤:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    # 如果没有ncu, 推荐安装来快捷更新/检查 (推荐)
    npm install -g npm-check-updates

    # 在hexo根目录下输入,查看当前可更新包
    ncu 
    # 更新packag.json文件 (当前目录)
    ncu -u  # 注意这样会更新所有模块到最新版本,可能有bug, 如果不需要的手动编辑修改

    # 更新全局的插件模块
    npm update -g  # 可选

    # 读取package.json进行更新
    npm install --save 

    # 修复安全问题/漏洞(完成全部升级)
    npm audit fix

  4. 完成升级, 为保险起见, 先清理一下再用 hexo clean && hexo g -d

0x05.npmの机制

上面说的主要是操作方式, 但是不知原理的做事风格实在很难对我胃口, 所以我还是单独补上这一部分, 后续如果深入研究了会把npm前世今生 也抽取为单独的文章. 这次就以hexo根目录和highlight.js的目录来简单解释一下. (注意**以下针对npm版本<6.0.** 因6.0之后很多机制发生了改进,等待更新补充)

首先, 我们关注三个npm 命令 : install, update, run build ,在对npm没有基础的印象的时候 ,可以先把它理解为mvn ,yum 或者常见的包管理工具, 本质是为了更方便的去安装js文件库 . 然后先看install 命令.

1. install

在hexo根目录下执行npm install ,它会默认读取当前目录下的package.json文件里的依赖模块到node_modules文件夹中, 整个过程大体是**3步**:

  1. 敲下install命令, 读取package.json 文件, 向远端仓库查询包含模块压缩包地址
  2. 下载压缩包, 存放在本地npm仓库
  3. 解压压缩包内容到当前目录的node_modules

需要注意的是, 不同于mvn先检查本地,再检查远程的逻辑, npm 只会先检查当前目录的node_modules , 而不会去检查本地npm仓库, 所以只要当前目录没检查到, 就会去远端重新执行上述操作.

2. update

字面意义一样, 更新已经安装过的模块, 比如highlight.js 升级它的版本, 类似常见的包管理工具, 它有一个**远端仓库**版本, 以及一个本地库版本, 从二者中选择符合条件的最新的一个安装

并且你可以通过npm info highlight.js 来查看包的最新信息, 这里面有两个关键信息, 一个是它最新的版本号latest: 9.13.1 , 一个是二进制包.tarball: https://addr.tgz , 其实你手动下载这个压缩包, 然后放到目录下解压, 也就是这个模块的源码了. install / update 命令的本质也就是这样的.

不同OS下npm的本地仓库(缓存)地址可能不一样, 通过npm config get cache 可以获得准确地址, 这下面就像mvn的.m2 文件夹一样, 里面存放了所有的本地包. 然后你浏览一下,可以发现它的结构如下:

1
2
3
4
5
6
7
8
$ ls highlight.js/*/*  #可以看到核心还是两个文件,压缩包和配置json文件
#highlight.js/9.11.0:
- package/package.json
- package.tgz

#highlight.js/9.13.1:
- package/package.json
- package.tgz

3. build

这个其实和上面的npm命令并不属于一个系列, 这个应该属于node 编译的系列? 后面补充吧, 总之需要package.json中对应存在相应的脚本.

4. 重大改动

npm 5之后, 在package.json的基础上 , 增加了 package-lock.json 文件, 用于锁定安装结构/版本 ,它的内容和node_modules 的文件结构一一对应.

友情提示: 在不太熟悉fe的情况下不要大改主题CSS. 很多适配问题可能会让你crazy.

参考文章: