shokaX主题插件文档

发布于 2023/01/14 字数统计 2,476 字阅读时长 13 分钟

什么是shokaX插件

shokaX插件系统提供了一个无需修改主题文件的魔改方法
主要基于hexo filter功能实现
awesome-shokaX 中有大部分shokaX插件

此插件系统高度借鉴于Next,部分Next插件甚至可以直接运行(仅针对部分注入点)

如何安装插件

script式插件

此类插件为文件夹式,一般由一个js文件和一个views文件夹组成,安装步骤如下:

在hexo环境根目录下创建scripts文件夹,并将js文件放置于其中
将views文件夹复制到hexo环境根目录下
如有README.MD文件请查看其中说明

随后hexo s即可

npm包式

此类插件为npm包,直接使用包管理器安装即可

如何编写插件

在开始之前

导言

shokaX插件的API和NextInjectAPI高度一致,所以本文未覆盖到的点位可以在评论区咨询或者参阅NextInjectsAPI

shokaX插件基于hexo script实现,因此你应该有一些编写hexo script的经验

注入点

shokaX插件在插入模板时需要指定点位,截止本文写就时,可用点位见下表:
模板点位:

代码名	点位	描述
head	文件头部	在`</head>`标签前注入模板
sidebar	侧栏	在social区域上方注入模板
rightNav	导航栏右侧	在日夜模式切换和搜索的右侧注入模板
postMeta	文章信息	在card的字数右侧注入模板
postBodyEnd	文章尾部	在文章的尾部注入模板
footer	页面底部	在页面底部注入模板
comment	评论区	在评论区注入模板(在主题评论上方)
bodyEnd	文件尾部	在`</body>`标签前注入模板
status	页脚状态	在备案号及版权说明之前

样式点位:

所有样式点位注入时均可覆盖主题样式

代码名	点位	描述
variable	变量	注入CSS变量
mixin	混合	注入mixin
style	样式	注入CSS样式

基础语法

注入模板

在一切之前,你应该创建一个js文件,随后写入如下内容:

hexo.extend.filter.register("theme_inject", function (injects) {});

这段代码的意思是注册一个基于theme_inject事件的过滤器
然后准备一个pug文件,下面以example.pug作为例子

div(id="test")
	p(id="test1") hello world

如果是js文件式,应将模板和样式放置于views文件夹中,npm式与js平级即可

随后修改js文件:

hexo.extend.filter.register("theme_inject", function (injects) {
  injects.footer.file("example", "views/example.pug", {}, { cache: true });
});

随后启动hexo s,你会发现页面底部出现了hello world
这行代码的意义如下:

injects.footer // 此处为过滤器的传入参数,即为shokaXInjectAPI // 此处为注入点,可参考上文的代码名
  .file(
    // 直接注入一个文件
    "example", // 名称,应当好记且不重复
    "views/example.pug", // 文件,以hexo环境根目录为根目录
    {}, // locals变量
    { cache: true }, // 是否需要缓存(如果组件内容随页面而变动,请填false)
  );

此外,还有raw方法,格式为:

raw(
  "example", //名称
  "<p>hello world</p>", // 模板
);

注入样式

还是这个js,自己准备一个example.styl放置于views文件夹,修改代码为:

hexo.extend.filter.register("theme_inject", function (injects) {
  injects.footer.file("example", "views/example.pug", {}, { cache: true });
  injects.style.push("views/example.styl");
});

代码意义同上,但style点位仅有push方法

更高级一点

插件格式

这里说明一下shokaX插件格式,以便在awesome-shokaX中发布,格式如下:

views //储存模板和样式(文件夹)
xxx.js //插件主程序
README.MD //插件的自述和注意事项

npm包只需要发布即可

常见问题

在npm中发布的包中,shokaXInjectsAPI的路径应使用如下格式:

path.join(__dirname, "file.xxx");

结语

如果有本文未覆盖到的点位或出现问题,可在评论区询问

shokaX