Static Pages / Twig

Renders documents via twig templates. This package is part of the Static Pages project.

Uses Twing and Marked packages under the hood.

Usage

import twig from '@static-pages/twig';

const renderer = twig({
	viewsDir: 'myViews',
});

const pageData = {
	title: 'Page header',
	url: 'some/page',
	content: 'My Content',
	view: 'content'
};

renderer(pageData); // returns the rendered page in a promise

Options

Option	Type	Default value	Description
view	string | (d: Data) => string	(data.view ?? 'main') + '.twig'	Template to render. If it's a function it gets evaluated on each render call.
views	Record<string, string>	undefined	Templates stored in memory, accessed without a filesystem implementation.
viewsDir	string | string[]	undefined	One or more directory path where the templates are found.
fs	NodeJS FS API	node:fs module	Using the viewDir impiles you are using a filesystem. Here you can provide a custom implementation for that.
filters	TwigFilters	{}	Filters in an object that gets loaded to the twig environment.
functions	TwigFunctions	{}	Functions in an object that gets loaded to the twig environment.
configure	(env: TwingEnvironment) => void	() => undefined	Allows advanced configuration with access to the env twig environment.
markedEnabled	boolean	true	Register a markdown filter; uses marked.
markedOptions	MarkedOptions	see markedOptions section	Custom options for the marked markdown renderer.

Custom types used in the table above:

type TwigFunctions = Record<string, TwingCallable<unknown>>;
type TwigFilters = Record<string, TwingCallable<unknown>>;

Example for TwigFunctions and TwigFilters:

import { twig, raw } from '@static-pages/twig';

const renderer = twig({
	functions: {
		asset(_context, asset: string) {
			return new URL(asset, '/site/assets/').toString();
		},
	},
	filters: {
		json(_context, data) {
			return raw(JSON.stringify(data, null, '\t'));
		},
	}
});

Functions and filters can be async or sync. No restrictions like the underlying Twing package makes where you allowed to use async functions only.

Everything provided by Twing and Marked is also exported from this package for advanced use cases, see twing and marked exports.

markedOptions defaults

This package uses the default options of the official marked defaults:

In twig template files, the custom markdown filter allows you to pass markdown options to the underlying markdown renderer. Example:

{{ '~~strike~~'|markdown({ gfm: false }) }}

<p>~~strike~~</p>

~~strike~~ converted to <del>strike</del> when gfm is true (default)

Additionally there is an inline option added to the available options. This removes the paragraph tags. Example:

{{ '[foo](bar)'|markdown({ inline: true }) }}

<a href="bar">foo</a>