Tag

A tag allows users to quickly and easily insert snippets into their posts.

Synopsis

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

Two arguments will be passed into the tag function: args and content. args contains the arguments passed into the tag plugin and content is the wrapped content from the tag plugin.

Since the introduction of asynchronous rendering in Hexo 3, we are using Nunjucks for rendering. The behavior may be somewhat different from that in Swig.

Unregister Tags

Use unregister() to replace existing tag plugins with custom functions.

hexo.extend.tag.unregister(name);

Example

const tagFn = (args, content) => {
 content = "something";
 return content;
};

// https://hexo.io/docs/tag-plugins#YouTube
hexo.extend.tag.unregister("youtube");

hexo.extend.tag.register("youtube", tagFn);

Options

ends

Use end tags. This option is false by default.

async

Enable async mode. This option is false by default.

Examples

Without End Tags

Insert a Youtube video.

hexo.extend.tag.register("youtube", function (args) {
 var id = args[0];
 return (
 '<div ><iframe width="560" height="315" src="http://www.youtube.com/embed/' +
 id +
 '" frameborder="0" allowfullscreen></iframe></div>'
 );
});

With End Tags

Insert a pull quote.

hexo.extend.tag.register(
 "pullquote",
 function (args, content) {
 var className = args.join(" ");
 return (
 '<blockquote  +
 className +
 '">' +
 content +
 "</blockquote>"
 );
 },
 { ends: true },
);

Async Rendering

Insert a file.

var fs = require("hexo-fs");
var pathFn = require("path");

hexo.extend.tag.register(
 "include_code",
 function (args) {
 var filename = args[0];
 var path = pathFn.join(hexo.source_dir, filename);

 return fs.readFile(path).then(function (content) {
 return "<pre><code>" + content + "</code></pre>";
 });
 },
 { async: true },
);

Front-matter and user configuration

Any of the following options is valid:

hexo.extend.tag.register('foo', function (args) {
 const [firstArg] = args;

 // User config
 const { config } = hexo;
 const editor = config.author + firstArg;

 // Theme config
 const { config: themeCfg } = hexo.theme;
 if (themeCfg.fancybox) // do something...

 // Front-matter
 const { title } = this; // article's (post/page) title

 // Article's content
 const { _content } = this; // original content
 const { content } = this; // HTML-rendered content

 return 'foo';
});

index.js

hexo.extend.tag.register("foo", require("./lib/foo")(hexo));

lib/foo.js

module.exports = hexo => {
 return function fooFn(args) {
 const [firstArg] = args;

 const { config } = hexo;
 const editor = config.author + firstArg;

 const { config: themeCfg } = hexo.theme;
 if (themeCfg.fancybox) // do something...

 const { title, _content, content } = this;

 return 'foo';
 };
};