Static Pages / Nunjucks Writer

Renders page data via Nunjucks templates.

Uses the Nunjucks package under the hood. Everything provided by Nunjucks is also exported from this package (for advanced configuration).

This package is part of the StaticPagesJs project, see:

• Documentation: staticpagesjs.github.io
• Core: @static-pages/core

Options

Option	Type	Default value	Description
view	string | (d: Data) => string	main.html	Template to render. If it's a function it gets evaluated on each render call.
viewsDir	string | string[]	views	One or more directory path where the templates are found.
outDir	string	dist	Directory where the rendered output is saved.
outFile	string | (d: Data) => string	see outFile defaults section	Path of the rendered output relative to outDir.
onOverwrite	(d: string) => void	console.warn(...)	Callback function that gets executed when a file name collision occurs.
onInvalidPath	(d: string) => void	console.warn(...)	Callback function that gets executed when a file name contains invalid characters.
globals	object	{}	Additional properties loaded to the nunjucks environment as globals.
functions	Record<string, Function>	{}	Functions in an object that gets loaded to the nunjucks environment.
filters	Record<string, Function>	{}	Filters in an object that gets loaded to the nunjucks environment.
advanced	(env: TwingEnvironment) => void	() => undefined	Allows advanced configuration via access to the env nunjucks environment.
showdownEnabled	boolean	true	Register a markdown filter; uses showdown.
showdownOptions	showdown.ConverterOptions	see showdownOptions section	Custom options for the showdown markdown renderer.

Example for filters and functions:

import { runtime as nunjucksRuntime } from '@static-pages/nunjucks-writer';
export const myFiltersOrFunctions = {
	asset(asset: string) {
		return new URL(asset, '/site/assets/').toString();
	},
	json_formatted: d => new nunjucksRuntime.SafeString(JSON.stringify(d, null, 4)),
};

outFile defaults

The default behaviour is to guess file path by a few possible properties of the data:

• if data.url is defined, append .html and use that.
• if data.header.path is defined, replace extension to .html and use that.
• if nothing matches call the onInvalidPath handler with undefined file name.

showdownOptions defaults

This package uses a sligthly modified defaults compared to the official Showdown defaults:

{
	simpleLineBreaks: true,
	ghCompatibleHeaderId: true,
	customizedHeaderId: true,
	tables: true,
}