Hexo插件开发步骤
Hexo的插件嵌入有两种方式,一种是通过脚本(Scripts)的方式引入,一种是通过插件(Packages)的方式将自定义的插件内容发布到npm上。本文主要介绍第二种,如果您的代码很简单,建议您编写脚本,您只需要把 JavaScript 文件放到主题目录的 scripts
文件夹,在启动时就会自动加载。具体操作可参考 Hexo 博客每天自动生成每日早报文章 中2.2相关介绍。
下面是引用官方的一段话,开发Hexo
插件至少要包含 2 个文件:一个是主程序index.js
,另一个是 package.json
,描述插件的用途和所依赖的插件。package.json
中至少要包含 name
, version
, main
属性。
链接直达:https://hexo.io/zh-cn/docs/plugins
如果您的代码较复杂,或是您想要发布到 NPM 上,建议您编写插件。首先,在
node_modules
文件夹中建立文件夹,文件夹名称开头必须为hexo-
,如此一来 Hexo 才会在启动时加载;否则 Hexo 将会忽略它。文件夹内至少要包含 2 个文件:一个是主程序,另一个是
package.json
,描述插件的用途和所依赖的插件。
1
2
3 .
├── index.js
└── package.json
package.json
中至少要包含name
,version
,main
属性,例如:
1
2
3
4
5 package.json{
"name": "hexo-my-plugin",
"version": "0.0.1",
"main": "index"
}
一、创建插件项目
创建一个新的目录来存放你的插件项目,文件夹名称开头必须为 hexo-
,例如 hexo-footer-plugin
可在任意目录创建,为方便测试也可直接在Hexo
项目的node_modules
目录下创建
1 | mkdir hexo-footer-plugin |
进入该目录
1 | cd hexo-footer-plugin |
初始化一个新的 npm 项目
1 | npm init |
使用npm init
初始化有操作向导,会引导你一步步输入package.json
文件的不同参数。
也可使用npm init -y
初始化一个仅包含默认参数的package.json
文件
1 | { |
然后自行修改,例如
1 | { |
在发布npm包时,仓库信息(repository)是一个可选字段,但建议填写。仓库信息可以帮助其他开发者更容易地找到和贡献代码。如果你不想填写仓库信息,可以省略这个字段。
二、编写插件代码
2.1、介绍
可参考官方文档进行开发
工具
您可以使用 Hexo 提供的官方工具插件来加速开发:
- hexo-fs:文件 IO
- hexo-util:工具程式
- hexo-i18n:本地化(i18n)
- hexo-pagination:生成分页数据
除了辅助函数(Helper),Hexo的插件还可划分为不同类型:控制台 (Console)、部署器 (Deployer)、过滤器 (Filter)、生成器 (Generator)、迁移器 (Migrator)、处理器 (Processor)、渲染引擎 (Renderer)、标签 (Tag)。
Hexo初始化的时候会相应加载插件列表,代码详见 node_modules\hexo\lib\hexo\index.js
1 | // Load internal plugins |
插件加载依托于load_plugins.js
,其主要函数有loadModules
、loadScripts
loadModules : 调用loadModuleList
读取package.json
,从而进一步加载插件列表(自带&第三方插件)
loadScripts : 加载脚本类插件(自带&主题scripts下的脚本)
1 | module.exports = ctx => { |
部分插件如果存在编译错误则Hexo会无法正常启动且输出错误日志,根据日志检查错误相应调整即可。
2.2、开发示例
在你的插件目录中创建一个 index.js
文件,并编写你的插件代码。例如:
1 | hexo.extend.filter.register('after_post_render', function(data){ |
假设我们需要做一个给文章添加版权声明的插件,hexo-footer-plugin
,创建 index.js
文件如下
1 | hexo.extend.filter.register('after_post_render', function(data){ |
这段代码 通过hexo.config
获取配置文件中的特定参数,配置项位于 hexo-footer-plugin
下的copyright_owner
,用于配置版权所有人,以下是如何获取这个配置参数的示例:
1 | const { config } = hexo; |
在这段代码中,我们首先从 hexo
实例中获取配置对象 config
。然后,我们通过点符号访问嵌套的配置项。注意,我们使用了可选链 ?.
来避免在配置项不存在时抛出错误。
如果 hexo-footer-plugin
或 copyright_owner
在配置文件中不存在,copyrightOwner
将保持未定义状态,而不会引发错误。
2.3、本地测试
2.3.1、初始化Hexo项目
我们重新初始化一个Hexo项目
1 | hexo init blog |
初始化好后可以先执行三连命令运行看下效果
1 | hexo clean && hexo g && hexo s |
2.3.2、安装插件依赖
1、通过 npm install
安装
在你的 Hexo 项目目录中,使用以下命令将本地插件链接到你的 Hexo 项目:
1 | npm install /path/to/your/hexo-footer-plugin |
例如我Hexo项目目录为 D:\hexo\test\blog
,插件存放目录为 D:\hexo\plugins\hexo-footer-plugin
执行安装命令,由于npm安装较慢,我使用的cnpm进行安装
1 | cnpm install ../../plugins/hexo-footer-plugin |
可以看到控制台提示成功添加一个依赖,插件名称 hexo-footer-plugin
版本号 ^1.0.0
我们到Hexo项目node_modules
检查一下
再检查下Hexo项目根目录下package.json
引入的依赖 dependencies
或者通过命令 npm ls
查看引入的依赖
2、通过 npm link
安装
或者,你也可以使用 npm link
命令来创建一个全局链接,然后在 Hexo 项目中使用这个链接:
以管理员权限执行命令,否则会出现 npm ERR! errno -4048 错误
1 | cd /path/to/your/hexo-footer-plugin |
更多关于 npm link
命令的内容详见 npm link 基本使用
执行npm ls
查看link是否创建成功
检查Hexo项目根目录 package.json
文件,如果没有 dependencies
部分,可以手动创建一个。然后,添加你链接的包的名称和版本。例如,如果你链接的包名为 my-package
,你可以这样添加:
1 | { |
例如此处我需要修改为
1 | { |
3、手动引入依赖
直接复制插件目录 hexo-footer-plugin
到Hexo项目 node_modules
文件夹内
修改Hexo项目根目录 package.json
文件,在dependencies
部分添加插件依赖
1 | { |
2.3.3、修改配置文件
在Hexo主配置文件 _config.yml
中添加插件的配置,注意不是主题的_config.yml
1 | hexo-footer-plugin: |
也有说需要添加下面这条配置的,我不添加也是可以的
1
2 plugins:
- hexo-footer-plugin这段代码是 Hexo 配置文件
_config.yml
中的一部分,用于指定 Hexo 博客项目所使用的插件。具体来说,这段代码的含义和作用如下:
- 含义:
plugins
:这是一个配置项,用于列出当前 Hexo 项目所使用的所有插件。- hexo-footer-plugin
:这是插件列表中的一个条目,表示当前项目使用了名为hexo-footer-plugin
的插件。- 作用:
- 插件管理:通过在
_config.yml
文件中列出插件,Hexo 在启动时会自动加载这些插件,并执行插件中定义的各种功能。- 功能扩展:
hexo-footer-plugin
是一个自定义插件,通过在_config.yml
中声明它,Hexo 会在生成博客内容时调用该插件,从而实现特定的功能扩展。例如,在你的例子中,hexo-footer-plugin
可能用于在每篇文章的末尾添加版权声明。总结来说,这段代码的作用是告诉 Hexo 在生成博客内容时要加载并使用
hexo-footer-plugin
插件,以便实现该插件所提供的功能。
2.3.4、重新运行并测试插件
1 | hexo clean && hexo g && hexo s |
注意: 此处每次运行一定要执行 hexo clean
插件才会执行生效
能看到文章底部出现版权声明就说明插件运行成功了
控制台也会有相应日志输出
三、发布到 NPM
确保你的插件目录中包含 index.js
文件,这是插件的入口文件。
添加 README.md
文件,提供插件的详细说明、安装方法和使用示例。
添加 LICENSE
文件,声明你的插件使用的开源许可证。
如果你还没有 npm 账号,需要先注册一个:
1 | npm adduser |
如果你已经有账号,直接登录:
1 | npm login |
提示回车打开浏览器访问页面,无论注册或登录都需要获取一次性密码(One-time Password),即邮箱验证码
发布你的插件:
1 | npm publish |
控制台提示如下信息即代表发布成功
发布成功后可直接在NPM官网查询
如果要更新插件的话,改下版本号重新发布即可。
四、安装并使用插件
4.1、安装插件
安装前先将Hexo根目录下node_modules
目录以及package.json
刚才引入的依赖移除重新执行项目确保原配置已失效,或者重新初始化个Hexo项目。
在你的 Hexo 项目目录中,使用以下命令安装你的插件:
1 | npm install hexo-footer-plugin --save |
或者
1 | cnpm install hexo-footer-plugin --save |
如下
4.2、修改配置文件
在你的 Hexo 项目配置文件 _config.yml
中添加插件的配置:
1 | hexo-footer-plugin: |
4.3、重新运行并测试插件
1 | hexo clean && hexo g && hexo s |
注意: 此处每次运行一定要执行 hexo clean
插件才会执行生效
五、文档和宣传
在 GitHub 上创建一个仓库,并将你的插件代码推送到这个仓库。
在 README 文件中提供详细的安装和使用说明。
在 Hexo 社区或其他相关论坛宣传你的插件。
六、提交插件到 Hexo 插件列表
打开 Hexo 官方插件列表的 GitHub 仓库:hexojs/site。
点击右上角的 “Fork” 按钮,将仓库 fork 到你自己的 GitHub 账户。
克隆你 fork 的仓库到本地:
1 | git clone https://github.com/YOUR_GITHUB_USERNAME/site.git |
进入 source/_data/plugins
目录并创建your-plugin-name.yml
文件,添加你的插件信息。例如:
1 | description: A Hexo plugin to add a custom footer with copyright information to posts. |
提交并推送你的更改:
1 | git add source/_data/plugins/your-plugin-name.yml |
在 你的 GitHub 仓库页面中,点击 “New pull request” 按钮,提交你的更改给 Hexo 官方插件列表。
提交 pull request 后,Hexo 团队会审核你的插件。一旦审核通过,你的插件就会被添加到 Hexo 官方插件列表中。
参考