This post will introduce the development of a Hexo plugin hexo-stop-tag-plugins, which helps hexo users to disable built-in tag plugins / nunjucks syntax, and write with pure markdown syntax.
To be more precise, this post's contribution include:
You might want to check the below commit history and PR to understand the contribution.
hexo-stop-tag-plugins is available on the hexo plugins page https://hexo.io/plugins/disableNunjucks in the Pull Request: https://github.com/hexojs/hexo/pull/3573, and released in hexo 3.9.0 yesterday (check release note for details)
Image Source: https://github.com/hexojs
In my last post, I introduced steemblog, which is a blog service and tool built by 
https://steemblog.github.io/@robertyan/
During the creation of steemblog, we met issues such as Failed to build when markdown body contains special chars when we're synchronizing some Steem user's posts in markdown into steemblog.
For example, the {%s} string in the below code block from the post https://steemd.com/@oflyhigh/mfc-access , will break the conversion from post's source into html, with no html result returned.
sConnect.Format(TEXT("ODBC;DRIVER={%s};DSN='';DBQ=%s;"), sDriver, sDBInfo);
This issue happens because hexo enables tag plugins by default, which relies on the nunjucks syntax, and there's no settings to disable that by hexo users.
To make steemblog function well, we need to fix this issue.
What's more, this is a quite common issue complaint by a lot of hexo users. You can checkout relevant links and examples from my PR and issues, and examples are:
In order to overcome this pain for the hexo users who want to get more control over the tag plugins syntax, we implemented this hexo plugin hexo-stop-tag-plugins for those who suffered from the common issue.
To use this plugin, you can check out the description in the NPM package: hexo-stop-tag-plugins
It's as easy as install it with NPM.
$ npm install hexo-stop-tag-plugins --save
That's it. Then your post will be rendered by hexo as pure markdown, and you can use packages like marked as the renderer.
Below we'll introduce how the plugin is implemented.
The implementation of the plugin is not complex if you're familiar with hexo's source code. In project https://github.com/think-in-universe/hexo-stop-tag-plugins, we implemented the overrider.js to set the disableNunjucks property of renderer to true. Then hexo post renderer should skip the renderering with nunjucks.
We come up with this idea by reading thorough the renderer process of hexo, and look at relevant issues and pull requests in hexo repostiory.
/*
The module is created to disable the tag plugins (https://hexo.io/docs/tag-plugins)
and nunjucks syntax, which causes troubles in parsing markdown often
*/
'use strict';
const extensions = ['md', 'markdown', 'mkd', 'mkdn', 'mdwn', 'mdtxt', 'mdtext'];
module.exports = function(hexo) {
let stop_tag_plugins = true;
if (hexo.config.stop_tag_plugins === undefined || hexo.config.stop_tag_plugins === true) {
stop_tag_plugins = true;
} else {
stop_tag_plugins = false;
}
for (let ext of extensions) {
let renderer = hexo.render.renderer.get(ext);
if (renderer) {
renderer.disableNunjucks = stop_tag_plugins;
hexo.extend.renderer.register(ext, 'html', renderer);
}
}
};
/* global hexo */
'use strict';
var overrider = require('./lib/overrider');
overrider(hexo);
We also added sufficient test cases to test this plugin, which you can checkout in test folder.
However, what makes us frustration is that the code blocks in markdown are not renderered correctly after we set the disableNunjucks property, and only placeholder of the code block are displayed.
This should be an issue of hexo, and that leads us to fix the defect in hexo with PR #3573
To understand the issue, you can read more details in the PR: https://github.com/hexojs/hexo/pull/3573
The property disableNunjucks was introduced in PR #2593 by one contributor. However, it's not added correctly and leads to problems.
To fix that, we modified lib/hexo/post.js in hexojs/hexo repository, which returns content after the placeholders (like a code block) are replaced.
// Render with markdown or other renderer
return ctx.render.render({
text: data.content,
path: source,
engine: data.engine,
toString: true,
onRenderEnd(content) {
// Replace cache data with real contents
data.content = cacheObj.loadContent(content);
// Return content after replace the placeholders
if (disableNunjucks) return data.content;
// Render with Nunjucks
return tag.render(data.content, data);
}
}, options);
The PR #2593 that introduced the
disableNunjucks property didn't add tests. So, to assure the quality, added unit tests for the disableNunjucks property:
// test for PR [#3573](https://github.com/hexojs/hexo/pull/3573)
it('render() - (disableNunjucks === true)', () => {
const renderer = hexo.render.renderer.get('markdown');
renderer.disableNunjucks = true;
return post.render(null, {
content: fixture.content,
engine: 'markdown'
}).then(data => {
data.content.trim().should.eql(fixture.expected_disable_nunjucks);
}).then(data => {
renderer.disableNunjucks = false;
});
});
// test for PR [#3573](https://github.com/hexojs/hexo/pull/3573)
it('render() - (disableNunjucks === false)', () => {
const renderer = hexo.render.renderer.get('markdown');
renderer.disableNunjucks = false;
return post.render(null, {
content: fixture.content,
engine: 'markdown'
}).then(data => {
data.content.trim().should.eql(fixture.expected);
}).then(data => {
renderer.disableNunjucks = false;
});
});
exports.expected_disable_nunjucks = [
'Title
',
util.highlight(code, {lang: 'python'}),
'\n\nsome content
\n',
'Another title
',
'{% blockquote %}
'
,
'quote content
',
'{% endblockquote %}\n',
'{% quote Hello World %}
'
,
'quote content
',
'{% endquote %}'
].join('');
After this defect is fixed in hexo and released in hexo 3.9.0 version, we could say the hexo-stop-tags-plugin should work well for hexo users.
To make the plugin available to its users. We published it to NPM and hexo/plugins page.
The submission to hexo/plugins page is merged in PR: https://github.com/hexojs/site/pull/966
- name: hexo-stop-tag-plugins
description: Disable tag plugins for all markdown posts
link: https://github.com/think-in-universe/hexo-stop-tag-plugins
tags:
- markdown
- tag_plugins
- renderer
It takes a few days to have the plugin be reviewed and merged.
disableNunjucks property is set at renderer level and applied to all the posts. User may need another setting to make it only applied to some of the posts, which is more flexible.
picture made by me which combines GitHub and Steem logos
For anyone who wants to contribute to this project, feel free to fork https://github.com/think-in-universe/hexo-stop-tag-plugins, and submit Pull Requests.
Or please directly contact me (
To reviewers: this post is set to "development" category because it contains a new project (a hexo plugin), and defect fixing to "hexo" project contributed by myself. If you have any concern, feel free to reach out to me directly.