How to write a plugin for hexo

For a small side-project I was writing a tiny plugin to display widgets of different social media sites.

Since the documentation of Hexo is lacking I thought I'd write up how you can do this.

The plugin in my case was providing a tag. So something you can use with {\% something \%} which gets replaced by Hexo with markup.

The documentation says:

hexo.extend.tag.register(name, function(args, content){
  // ...
}, options);

That's largely correct.

What confused me is where hexo comes from. Turns out that you must not require it in your code or otherwise the consumer will see a large warning in his console, that hexo was already defined.

SyntaxError: Identifier 'hexo' has already been declared

The value of name is what will be used for the tag (something above). The argument args will contain a list of parameters passed with the tag. content will only be used if your tag is wrapping other content. In this case, the tag should have an end tag, which you can indicate with the options argument.

And that's it.