Hexo Renderers

Hexo Renderers is a public GitHub repository maintained by dimaslanjaka that bundles multiple Hexo theme renderer engines and helper functions into one installable plugin package.

What is Hexo Renderers?

Hexo Renderers provides a single entry point for loading the template engines Hexo uses to build themes: ejs, stylus, nunjucks, dartsass, pug, sass, markdown-it, rollup, and marked. It takes a _config.yml block as input and produces rendered HTML pages, stylesheets, and generated metadata during Hexo's build process. The plugin also includes custom helpers, a related-post generator, an auto post-asset-folder fixer, and a renderer cache strategy.

Key Features

• Multiple renderer engines — Supports ejs, stylus, nunjucks, dartsass, pug, sass, markdown-it, rollup, and marked, each enabled or disabled through the renderers.engines configuration array.
• Custom helpers — Adds custom helpers usable inside posts and layouts, including related post helpers; example views are available in the repository's views folder.
• meta.json generator — When enabled via renderers.generator, generates a meta.json file served at the site root, e.g. http://example.com/meta.json.
• Post asset folder fixer — Automatically fixes invalid post asset folder paths, with a toggle in renderers.fix.
• HTML fixer — When renderers.fix.html is true, escapes invalid HTML tags into HTML entities and lets you whitelist custom tag names through html_tags.
• Renderer cache strategy — Adds cache options to renderers; for example marked.cache defaults to true in this plugin and markdown.cache can be set for markdown-it.
• Extensive markdown-it configuration — Supports preset selection, plugins (abbr, attrs, bracketed spans, sup, CJK breaks, sub, deflist, footnote, ins, mark, KaTeX, emoji with custom shortcuts), anchors, image handling (lazyload, root prefix, post assets), and inline mode.
• ESM with CommonJS shim — Version 3.0.0 migrated the plugin to ESM while providing a CommonJS shim, and it requires a patched markdown-it build for CommonJS compatibility.

Who is it for?

• Hexo theme developers — who want to support multiple template engines and need a single package to manage renderers, helpers, and rendering fixes.
• Bloggers using advanced Markdown — who want footnotes, KaTeX math, emoji shortcuts, custom attributes, and definition lists without manually wiring each markdown-it plugin.
• Site administrators — who need caching to speed up rebuilds, automatic asset folder correction, HTML cleaning, or a machine-readable meta.json for external tools.

What can you do with it?

• Theme developers: declare only the renderer engines you need through renderers.engines and have the plugin load exactly those, avoiding duplicate renderer packages.
• Content writers: use the markdown-it engine with a dozen preconfigured plugins — abbreviations, attributes, bracketed spans, superscript, subscript, CJK breaks, definition lists, footnotes, inserts, marks, KaTeX, and emoji with custom shortcuts.
• Maintainers: enable the HTML fixer to escape invalid HTML tags into entities and add custom tags to the html_tags list to prevent transformation, or enable caching to reduce rebuild time.

How does it work?

Install Hexo Renderers, then add a renderers block to your _config.yml listing the engines, generator features, and fix options you want. If you use the markdown-it engine, you must also install the patched CommonJS build of markdown-it from the repository's provided link, because the original markdown-it only supports ESM. At build time, Hexo loads the plugin, which activates the selected renderers, applies the markdown configuration (preset, plugins, anchors, images, inline), runs enabled generators, and applies requested fixes.