# @akashacms/renderers

> Consolidated support for multiple website content rendering tools in Node.js

Latest version **0.9.12** (published 2026-06-26) · ISC license · 0 weekly downloads

## Install

```sh
npm install @akashacms/renderers
pnpm add @akashacms/renderers
yarn add @akashacms/renderers
bun add @akashacms/renderers
```

## Health

**Score 55/100 (C)** — status: active.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.9.12 |
| Published | 2026-06-26 |
| First published | 2022-10-03 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=24.x |
| Dependencies | 10 |
| Unpacked size | 292.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | David Herron |
| Maintainers | reikiman |
| Keywords | static website generator, generator, watcher, watchFile, watching, cms, website, templates |

## Links

- npm: https://www.npmjs.com/package/@akashacms/renderers
- Repository: https://github.com/akashacms/rendering-engines
- Homepage: https://akashacms.github.io/rendering-engines/
- Issues: https://github.com/akashacms/rendering-engines/issues
- npm.io page: https://npm.io/package/@akashacms/renderers

## Dependencies (10)

- [ejs](https://npm.io/package/ejs.md) ^6.x
- [eta](https://npm.io/package/eta.md) ^4.6.x
- [less](https://npm.io/package/less.md) ^4.6.x
- [liquidjs](https://npm.io/package/liquidjs.md) ^10.27.x
- [nunjucks](https://npm.io/package/nunjucks.md) ^3.2.x
- [mahabhuta](https://npm.io/package/mahabhuta.md) ^0.9.x
- [handlebars](https://npm.io/package/handlebars.md) ^4.7.x
- [gray-matter](https://npm.io/package/gray-matter.md) ^4.0.3
- [markdown-it](https://npm.io/package/markdown-it.md) ^14.2.x
- [@asciidoctor/core](https://npm.io/package/@asciidoctor/core.md) ^4.x

## Recent versions

- 0.9.12 (latest) — 2026-06-26
- 0.9.11 — 2024-12-22
- 0.9.10 — 2024-12-17
- 0.9.9 — 2024-11-22
- 0.9.8 — 2024-11-15
- 0.9.7 — 2024-11-15
- 0.9.6 — 2024-11-14
- 0.9.5 — 2024-10-09
- 0.9.4 — 2024-03-08
- 0.9.3 — 2022-11-06
- 0.9.2 — 2022-10-08
- 0.9.1 — 2022-10-07
- 0.9.0 — 2022-10-03

## README

# Renderers - Consolidated support for multiple website content rendering tools in Node.js

This is `@akashacms/renderers@0.9` which maintains compatibility with akasharender@0.9.

The `@akashacms/renderers` package simplifies using any of several rendering tools, including Markdown (using Markdown-IT), AsciiDoc, LESS, and several template engines.

It can be used in any Node.js (or Deno or Bun) application.  While it was designed to be used in the AkashaCMS ecosystem, especially akasharender, it does not have direct dependencies any AkashaCMS feature.  Instead it can be integrated into any other application.

The purpose is to present a harmonized interface to any package whose purpose is rendering files used in website construction.  These packages fall into three categories:

* Template rendering engines like EJS, Handlebars or Nunjucks
* CSS rendering using LESS
* Document rendering using Markdown or AsciiDoctor

Links:

* Home page: https://akashacms.github.io/rendering-engines/index.html
* NPM: https://www.npmjs.com/package/@akashacms/renderers
* Introduction: https://akashacms.com/news/2022/09/renderers-package.html

## Installation

```
$ npm install @akashacms/renderers --save
```

In your source code add this:

```js
// CommonJS modules
const Renderers = require('@akashacms/renderers');
// ES6 modules
import {
    Configuration as RenderersConfiguration
} from '@akashacms/renderers';
```

The `Configuration` class handles configuration and organizing access to the rendering packages.  For CommonJS modules imported as shown here, this class is referenced as `Renderers.Configuration`.

```js
import {
    Configuration as RenderersConfiguration,
    Renderer
} from '@akashacms/renderers';
```

The `Renderer` class is how we encapsulate the rendering packages.  Each encapsulated package has a matching Renderer class that interfaces with the package.

## Usage

The model is that a file to be rendered has an input file name, and an output file name.  The input file is in a pre-rendered format, such as Markdown, and the output file is in its rendered format, such as HTML.

The _Configuration_ automatically loads the Renderer implementations contained in the package.  It is easy to write your own Renderer and add them to the Configuration.

Suppose you have a content file to render.  It can be rendered with the following code:

```js
import { promises as fsp } from 'fs';

import {
    Configuration as RenderersConfiguration
} from '@akashacms/renderers';

const renderers = new RenderersConfiguration({
    // possible configuration options
});

const inputFN = '/path/to/input.html.md';
const input = await fsp.readFile(inputFN, 'utf-8');
const renderer = renderers.findRendererPath(inputFN);
const renderContext = renderer.parseMetadata({
    fspath: inputFN,
    content: input
});
// parseMetadata looks for frontmatter, and will
// modify the renderingContext to have two new fields.
// `body` will have the main body of the input
// `metadata` will have the frontmatter as an object

const rendered = await renderer.render(renderContext);

// ...
const outputFN = renderer.filePath(inputFN);
fsp.writeFile(outputFN, rendered, 'utf-8');
```

The `findRendererPath` method searches the available Renderers for one which will handle the path.  Each Renderer has a `match` method which is used for matching file names.

The double extension, `.html.md`, is meant to convey that the input is Markdown and the output is HTML.

The `parseMetadata` method will examine a file to access any metadata values.  For the Markdown renderer, and most other renderers, this turns into looking for a frontmatter block that is formatted in YAML.

The `render` method renders the content and metadata in the `RenderingContext` object.  It produces an output formatted as per the renderer.

The output file name is computed by the Renderer using the `filePath` method.

You may want to render the Markdown file into a layout template.  If so, change the final bit to this:

```js
const layoutMetadata = {};
for (const yprop in renderContext.metadata) {
    layoutMetadata[yprop] = renderContext.metadata[yprop];
}
layoutMetadata.content = rendered;

const layoutFN = '/path/to/layouts/example.html.ejs';
const layout = await fsp.readFile(layoutFN, 'utf-8');
const layoutRenderer = renderers.findRendererPath(layoutFN);
const layoutRendered = layoutRenderer.render({
    fspath: layoutFN,
    content: layout,
    metadata: layoutMetadata
});
const outputFN = renderer.filePath(inputFN);
fsp.writeFile(outputFN, layoutRendered, 'utf-8');
```

This example uses an EJS formatted template.  This follows roughly the same pattern as above.

It starts by finding the renderer for the layout template using `findRendererPath`.

In this case we assume the template does not contain any metadata values.  Your application might want to support metadata in the layout template, in which case you can call `parseMetadata`.

The layout template should receive all metadata values.  This allows those values to be substituted into the template.  The example shows us computing the metadata from the values found in the original document.  To that we add a value, `content`, which is the rendered output from the first stage.

## Supported rendering engines

The supported engines are:

Name       | Extension          | Description
-----------|--------------------|------------
AsciiDoc   | `.html.adoc`       | Supports AsciiDoctor documents using [@asciidoctor/core](https://www.npmjs.com/package/@asciidoctor/core)
Markdown   | `.html.md`         | Supports Markdown documents using [Markdown-it](https://www.npmjs.com/package/markdown-it)
LESS       | `.css.less`        | Supports compiling LESS files to CSS using [LESS](https://www.npmjs.com/package/less)
EJS        | `.html.ejs`        | EJS using [EJS](https://www.npmjs.com/package/ejs)
ETA        | `.html.eta`        | ETA using [ETA](https://www.npmjs.com/package/eta)
Handlebars | `.html.handlebars` | Handlebars using [Handlebars](https://www.npmjs.com/package/handlebars)
JSON       | `.html.json`       | Supports rendering a JSON document through a template to produce HTML
Liquid     | `.html.liquid`     | LiquidJS using [LiquidJS](https://www.npmjs.com/package/liquidjs)
Nunjucks   | `.html.njk`        | Nunjucks using [Nunjucks](https://www.npmjs.com/package/nunjucks)

---
_Source: https://npm.io/package/@akashacms/renderers · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
