Disclaimer: For explaination on Tag Plugin and Scripts in Hexo, you may take a look of this post.

Plugin

Be Careful! Don’t mix Plugin, Tag, and Tag Plugin in Hexo, even though they look extremely similar.

Usually, Plugin are for complicated functions. Yet if you want to publish your custom Tag Plugin to the NPM registry or even shown on the Hexo Community Page, Plugin would be a very good choice.

From Script to Plugin

Assume you already have a script call index.js, and you want to turn it into package, you may do the following:

1. Navigate node_modules folder in your project folder. This is the folder where Hexo stored all the packages for your blog. Create a folder inside and the name must begin with hexo- or Hexo will ignore it.

2. Your folder must contain at least two files: the actual JavaScript code and package.json file that describes the purpose of the plugin and sets its dependencies.

   .
   ├── index.js
   └── package.json
   

3. In package.json, it should at least have the name, version and main entries set.

   {
       "name": "hexo-my-plugin",
       "version": "0.0.1",
       "main": "index"
   }
   

4. In the root package.json of your hexo project, you also need to list your plugin as a dependency, for Hexo to detect and load it.
   Please remember that if your package contain other dependencies, also install and list them for testing and dubugging.

   {
       "name": "hexo-site",
       "version": "0.0.0",
       "private": true,
       "scripts": {
           "build": "hexo generate",
           "clean": "hexo clean",
           "deploy": "hexo deploy",
           "server": "hexo server"
       },
       "hexo": {
           "version": ""
       },
       "dependencies": {
           "hexo": "^7.3.0",
           ...
           "hexo-my-plugin": "0.0.1",
           "my-plugin-dependency1": "2.0.0",
           "my-plugin-dependency2": "2.0.0"
       }
   }
   

If you run command that check all the package after step 4, for exmaple hexo clean, it will check all the packages in node_modules and remove packages that are not publish on npm.

Publish Plugin to npm

To publish your package on the NPM registry, don’t forget you have to setup your account on npm first.

To color your personal Hexo Blog with more features, scripts and plugins are your powerful tools to use. Below we are trying to create our own tag plugin for the Hexo blog.

Tag Plugin

Be careful! Tag plugins are different from post tags.

Tag plugins are special type of syntax that you may use in your Markdown file.

Hexo has already provided some default Tag plugins like Block Quote and iframe.

Usage

For example, the syntax of iframe tag is:

{% iframe url [width] [height] %}

Let say I want to embed a video from me and my friends’ YouTube video:

{% iframe https://www.youtube.com/embed/XIOl6BU7s9I?si=yTYsHIXNM6o-Zl9Z 820 461%}

This is a image version of the post here

range-set:

range-set   ::= range ( logical-or range )*

logical-or:

logical-or  ::= ' '* '||' ' '*

referenced by: range-set

range:

To see the syntax and Railroad diagram version, goto here

Basic Structure

Package dependecies are a tuple of [major, minor, patch] with numeric values.

{
    "name": "project name",
    "version": "0.0.1",
    "description": "description of the project",
    "keywords": [
        "keyword 1",
        "keyword 2"
    ],
    "author": "John Doe",
    "dependencies": {
      "package-1": "~0.6.2",
      "package-2": ">=2.6.2"
    }
}

Version Range operator

Basic Range

For x in exmaple, see Advanced Range below.

Operator	Explaination	Example
=	package version must be exactly matched	1.0.0 := =1.0.0 (They are equivalent)
<	package version must be less than indicated	<2.0.0 :=version from 0.0.1 to 1.x.x
<=	package version must be less than or euqal to indicated	<=2.0.0 :=version from 0.0.1 to 2.0.0
>	package version must be greater than indicated	>2.0.0:= version from 2.0.1 to x (x >= 2)
>=	package version must be greater than or euqal to indicated	>=2.0.0 :=version from 2.0.0 to x (x >= 2)
||	joined one or more operator	>2.0.1 || <1.7.3 :=version greater than 2.0.1 or less than 1.7.3
space	Intersected one or more operator	>=2.0.1 <=1.7.3 :=version from 2.0.1 to 1.7.3 (inclusive)

Advanced Range

Advanced ranges may be combined in the same way as primitive comparators using space or ||.