@sidvind/build-nunjucks

Nunjucks filters and helpers for generating HTML static pages

Usage

It exports a single function taking the nunjucks Environment instance:

const configure = require('@sidvind/build-nunjucks')({
  /* options */
});
const env = new nunjucks.Environment(..);
configure(env);

With grunt-nunjucks-2-html:

nunjucks: {
  options: {
    configureEnvironment: require('@sidvind/build-nunjucks')({
      /* options */
    }),
  },
}

Options

assetDir

• Type: string
• Default: "public/assets"

Source directory to read assets from.

assetHash

• Type: Function
• Prototype: function(filename: string): string

Assign a custom hash function. Takes the filename and should return the calculated hash.

assetUrl

• Type: string
• Default: "assets/${path}${filename}.${ext}?${hash:10}" (e.g. "assets/js/site.min.js?1234567890")

Supports the following parameters:

• path: asset path.
• filename: asset filename without extension.
• ext: asset extension
• hash[:N]: asset hash, optionally limited to first N characters.
• mtime: asset file modification timestamp.

sri

• Type: boolean | "auto"
• Default: "auto"

Enable/disable SRI. The sri filter will only output the integrity value it enabled.

When set to auto the filter is enabled for production builds (NODE_ENV=production).

Filters

assetUrl filter

Generate a cache-buster URL for an asset.

Template:

<link rel="stylesheet" href="{{ 'css/site.min.css' | assetUrl }}">

Output:

<link rel="stylesheet" href="assets/css/site.min.css?e4202148fa903327c91d89f0c6fec4af">

The format can be customized by setting the assetUrl option.

sri filter

SRI integrity (hash) of an asset. See sri option to enable/disable. By default this does not output anything in development builds.

Template:

<link rel="stylesheet" .. integrity="{{ 'css/site.min.css' | sri('sha384') }}">

Output:

<link rel="stylesheet" .. integrity="sha384-zwJH9nUlOkCDg2d1r1c5jLqv8NQ2O9CHKIa0sAYozc0MD1aPSbNqGM9YY7+Sz6n1">

Globals

now global

Build timestamp (seconds since 1 jan 1970).

git global

Git metadata.

{
  "commit": "...",
  "branch": "my-branch"
}

Template:

<pre>{{ git | dump }}</pre>

Output:

<pre>{&quot;commit&quot;:&quot;9b27067&quot;,&quot;branch&quot;:&quot;feature/my-fancy-branch&quot;}</pre>

API - cachebuster.js

The module exports the the following functions:

hash(filename: string): string

Calculates the file hash (used by asset url).

mtime(filename: string): string

Get the file modification time.