# 什么是 shokaX 插件

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

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

# 如何安装插件

# script 式插件

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

  1. 在 hexo 环境根目录下创建 scripts 文件夹,并将 js 文件放置于其中
  2. 将 views 文件夹复制到 hexo 环境根目录下
  3. 如有 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. // 此处为过滤器的传入参数,即为 shokaXInjectAPI
footer. // 此处为注入点,可参考上文的代码名
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')

# 结语

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