Hexo NexT 高阶教程之 Injects

前世因

这要追溯到3月份,Mimi的PR:Adding Submodule,我们讨论了如何管理第三方依赖。LEAFERx提出了使用NPM管理会更好,他进行了实践PR:Extract leancloud-counter to plugins #677 #707。在我看来LEAFERx的方案并不好,因为复杂。所以要做到插件化,有两个必须达到的要求:

  1. 灵活与可扩展性,在插件中,我们就要能修改大部分内容。
  2. 操作简单,我们通过极少的代码集成我们想要的功能。

除此外,ivan-nginx还关心文档的问题,但如果能完全独立,存放在插件库中也不是什么大问题。在此期间,我也进行过尝试PR:Refactoring comments,毕竟现在的评论系统真的"烂",一堆if else。这次的重构是挺好的尝试,但我不敢轻易合,因为影响大(几乎所有人),而后来发现了另一个方案,是Hexo的一个插件hexo-inject,通过注入代码的方式实现定制内容,由于hexo本身与主题分离,它仅能提供4个注入点,可扩展性远远不够。但如果能在NexT中实现,就完全不同了,于是我提了PR:Add new filter type theme_inject

使用 Injects

Okay,缘由讲到这,接下来来体验下如何使用theme_inject。当然,如果你是小白,完全可以使用配置文件中的custom_file_path来添加自定义内容。如果想更加定义化,那么跟着我一步步走下去。Injects具体的定义见NexT文档。这里接下来是个例子,一步步集成gitter

注入布局

首先,我们在hexo或者theme的scripts创建一个js文件(名字随意),添加以下内容。只要是这里面的脚本,hexo运行时会执行它。

hexo.extend.filter.register('theme_inject', function(injects) {
  //名字路径等都可以随意修改,为了方便下文都以这里的定义为主
  injects.head.file('gitter', 'views/gitter.swig', {}, {cache: true});
});

第二步,我们创建views/gitter.swig文件,添加以下内容。

<script>
  ((window.gitter = {}).chat = {}).options = {
    room: 'your-room-name'
  }});
</script>
<script src="https://sidecar.gitter.im/dist/sidecar.v1.js" async defer></script>

hexo s运行,你可以看到右下角已经集成了gitter。

注入样式

接下来,我们调整下样式。在脚本中,多加样式的注入。

hexo.extend.filter.register('theme_inject', function(injects) {
  injects.head.file('gitter', 'views/gitter.swig', {}, {cache: true});
  injects.style.push('views/gitter.styl');
});

创建views/gitter.styl文件

.gitter-open-chat-button {
  background-color: slateblue;
  margin-bottom: .8rem;
  margin-right: 1rem;
  padding: .4rem .8rem;
  border-radius: .6rem;
  box-shadow: 0 0 .4rem #111;
  opacity: .9;
}

.gitter-open-chat-button:focus,.gitter-open-chat-button:hover {
  background-color: slateblue;
  box-shadow: 0px 0px 0.8rem #111;
}

.gitter-open-chat-button.is-collapsed {
  transform: translateY(150%);
}

.sidebar-toggle {
  margin-bottom: 18px;
}

再次运行,按钮的样式变咯,你觉得相对于原来是好看还是...?

制作NPM插件

开源的精神在于分享,当你将你的主题自定义之后,你可能会写一篇文章《如何实现在NexT中XXXX》。然后,Visitor看到后,跟着你一点点的改。虽然没什么问题。但毕竟“懒”才是原动力,如果我们能将这一切放入到一个NPM插件中,那么他们使用的时候,就只需要yarn add xxxx就行了。这将多方便呀!!!

接下来要实现是一个集合滑动到底部/头部和阅读进度的插件,最终效果见hexo-cake-moon-menu,以及我的博客右下角的那个按钮

为了能上传至NPM仓库,你首先需要在它上面创建一个账户:https://www.npmjs.com/,另外为了方便,我是用的是yarn作为命令行工具

初始化一个NPM包

新建一个文件夹,并在里面运行yarn init,会问你一系列的问题(如下面),完成后会初始化一个package.json

PS C:\Users\MrTT\Desktop\hexo-moon-menu> yarn init
yarn init v1.16.0
question name (hexo-moon-menu): @jiangtj/hexo-moon-menu
question version (1.0.0):
question description: Hallo
question entry point (index.js):
question repository url: https://github.com/jiangtj/hexo-theme-cake.git
question author: Mr.J
question license (MIT): LGPL-3.0
question private: false
success Saved package.json
Done in 99.85s.

name建议添加scope也就是@你的用户名,比如到时候有一样名字的包,无法上传

创建例子工程预览插件

你需要将你的插件上传上出(这步原本最后,但由于hexo会检测package.json来执行插件,所以必须先有插件),在当前项目中运行yarn publish --access public

添加一个.gitignore,如果默认情况下,npm也会依据它忽略不必要的文件

node_modules/
*.log
example/

运行以下命令,来创建例子项目

# 在example创建hexo项目
hexo init example
# 进入到example目录下
cd example
# 添加next主题
git clone https://github.com/theme-next/hexo-theme-next themes/next
# 切换主题配置
hexo config theme next
# 切换Gemini scheme, 这次的插件由于和展开侧边栏的冲突,所以Muse中暂时不支持,如果你感兴趣可以自行在Muse中实现
hexo config theme_config.scheme Gemini
# 运行预览
hexo s

关联插件

# 添加依赖
yarn add "@jiangtj/hexo-moon-menu"
# 将插件创建引用,方便调试
cd ..
yarn link
cd example
yarn link "@jiangtj/hexo-moon-menu"
# 运行预览,由于没做说明所以没什么变话
hexo s

布局与样式

接下来将我的项目中hexo-cake-moon-menu以下部分复制到你的插件项目

  • default.yaml 默认配置
  • moon-menu.swig 菜单的布局
  • moon-menu.styl 菜单的样式

在上面的Injects使用中,你能体会到重点在于js脚本,样式等都是通过它进行组织的,所以样式我这边忽略了,如果你想研究可以查看那些

脚本

package.json 中的 main 定义了脚本的入口文件,默认是index.js,所以我们创建它,并添加以下内容

// 需要引入的依赖
const yaml = require('js-yaml');
const fs = require('fs');
const path = require('path');

hexo.extend.filter.register('theme_inject', function(injects) {

  // 需要原本的按钮
  hexo.theme.config.back2top.enable = false;

  // 读取默认配置文件
  // __dirname至该文件的绝对目录,需要注意这里的位置如果不使用path获取绝对路径,文件读出会异常(建议你尝试,体验npm的坑)
  let defaultConfig = yaml.safeLoad(fs.readFileSync(path.join(__dirname, 'default.yaml')));
  // 合并默认配置与hexo里的moon_menu配置
  let moonMenu = Object.assign(defaultConfig, hexo.config.moon_menu);

  // 重新组织菜单,排序等
  let moonMenuArr = Object.keys(moonMenu)
    .map(key => moonMenu[key])
    .map(item => {
      item.order = item.order || 0;
      if (item.enable === undefined) {
        item.enable = true;
      }
      return item;
    })
    .filter(item => item.enable)
    .sort((a, b) => a.order - b.order);
  
  // 添加布局
  injects.bodyEnd.file('moon-menu', path.join(__dirname, 'moon-menu.swig'), {menus: moonMenuArr}, {cache: true, only: true});
  // 添加样式
  injects.style.push(path.join(__dirname, 'moon-menu.styl'));

});

忘了,你需要添加js-yaml依赖用于解析yaml

cd ..
yarn add js-yaml
cd example
hexo s

再次运行预览,你就可以看到按钮添加到你的例子工程中拉

上传

完成后记得别忘记上传yarn publish --access public,然后赶紧在自己的博客中试下把yarn add @jiangtj/hexo-moon-menu

如果你希望更多看到与使用你的插件,可以提交PR至 Awesome-NexT

后世果

虽然这个theme_inject已经合并了,但还有许多需要改进

  • Inject的内容可以通过注入的优先级(过滤器优先级)来调整位置,所以有必要的将部分已有的调整实现方式,以便用户调整其出现的位置
  • 有必要使NexT更结构化,以提供更多的注入点
  • 评论系统的重构PR关闭了,多方面原因,我计划基于theme_inject重新重构它(有时间的话,咕咕咕)

Post author: Mr.J
Post link: https://www.dnocm.com/articles/beechnut/hexo-next-injects/
Copyright Notice: All articles in this blog are licensed under BY-NC-SA unless stating additionally.

最后编辑于
©著作权归作者所有,转载或内容合作请联系作者
  • 序言:七十年代末,一起剥皮案震惊了整个滨河市,随后出现的几起案子,更是在滨河造成了极大的恐慌,老刑警刘岩,带你破解...
    沈念sama阅读 143,906评论 1 305
  • 序言:滨河连续发生了三起死亡事件,死亡现场离奇诡异,居然都是意外死亡,警方通过查阅死者的电脑和手机,发现死者居然都...
    沈念sama阅读 61,698评论 1 257
  • 文/潘晓璐 我一进店门,熙熙楼的掌柜王于贵愁眉苦脸地迎上来,“玉大人,你说我怎么就摊上这事。” “怎么了?”我有些...
    开封第一讲书人阅读 95,242评论 0 213
  • 文/不坏的土叔 我叫张陵,是天一观的道长。 经常有香客问我,道长,这世上最难降的妖魔是什么? 我笑而不...
    开封第一讲书人阅读 41,257评论 0 182
  • 正文 为了忘掉前任,我火速办了婚礼,结果婚礼上,老公的妹妹穿的比我还像新娘。我一直安慰自己,他们只是感情好,可当我...
    茶点故事阅读 49,076评论 1 260
  • 文/花漫 我一把揭开白布。 她就那样静静地躺着,像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上,一...
    开封第一讲书人阅读 38,912评论 1 178
  • 那天,我揣着相机与录音,去河边找鬼。 笑死,一个胖子当着我的面吹牛,可吹牛的内容都是我干的。 我是一名探鬼主播,决...
    沈念sama阅读 30,509评论 2 274
  • 文/苍兰香墨 我猛地睁开眼,长吁一口气:“原来是场噩梦啊……” “哼!你这毒妇竟也来了?” 一声冷哼从身侧响起,我...
    开封第一讲书人阅读 29,255评论 0 168
  • 想象着我的养父在大火中拼命挣扎,窒息,最后皮肤化为焦炭。我心中就已经是抑制不住地欢快,这就叫做以其人之道,还治其人...
    爱写小说的胖达阅读 29,145评论 6 235
  • 序言:老挝万荣一对情侣失踪,失踪者是张志新(化名)和其女友刘颖,没想到半个月后,有当地人在树林里发现了一具尸体,经...
    沈念sama阅读 32,613评论 0 214
  • 正文 独居荒郊野岭守林人离奇死亡,尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 29,376评论 2 216
  • 正文 我和宋清朗相恋三年,在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 30,733评论 1 231
  • 白月光回国,霸总把我这个替身辞退。还一脸阴沉的警告我。[不要出现在思思面前, 不然我有一百种方法让你生不如死。]我...
    爱写小说的胖达阅读 24,287评论 0 32
  • 序言:一个原本活蹦乱跳的男人离奇死亡,死状恐怖,灵堂内的尸体忽然破棺而出,到底是诈尸还是另有隐情,我是刑警宁泽,带...
    沈念sama阅读 27,196评论 2 213
  • 正文 年R本政府宣布,位于F岛的核电站,受9级特大地震影响,放射性物质发生泄漏。R本人自食恶果不足惜,却给世界环境...
    茶点故事阅读 31,644评论 3 211
  • 文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹,春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 25,651评论 0 9
  • 文/苍兰香墨 我抬头看了看天上的太阳。三九已至,却和暖如春,着一层夹袄步出监牢的瞬间,已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 26,059评论 0 169
  • 我被黑心中介骗来泰国打工, 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留,地道东北人。 一个月前我还...
    沈念sama阅读 33,644评论 2 233
  • 正文 我出身青楼,却偏偏与公主长得像,于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子,可洞房花烛夜当晚...
    茶点故事阅读 33,789评论 2 237