@injms/quack-nunjucks-filters

🦆 Quack Nunjucks filters

A collection of small, simple, opinionated filters that can be used with Nunjucks and Eleventy.

What do these filters do?

cssmin

Takes a string of CSS and minifies it.

debug

Does nothing apart from display the thing in the console.

{{ "hello world" | debug }} // returns "hello world" unchanged and logs "hello world" in the console

Can be used multiple times so you can see what something is before and after it goes through a filter:

{{ "22 July 2020" | debug | humandate('pt') | debug }}

// returns "22 de julho de 2020"; also logs "22 July 2020" and then "22 de julho de 2020" in the console.

humandate

Takes a date that can be understood by Date.parse() and returns a human readable version.

{{ '2020-06-23T20:07:58.800Z' | humandate }} // 23 July 2020

Supports internationalisation - pass in a langauage or a language-country code:

{{ '2020-06-23T20:07:58.800Z' | humandate('pt') }} // 23 de junho de 2020

{{ '2020-06-23T20:07:58.800Z' | humandate('es-HN') }} // 23 de junio de 2020

markdownify

Takes a string of Markdown and returns a string of HTML. A simple wrapper around MarkdownIt.

{{ '*bold* text' | markdownify | safe }} // <b>bold</b> text

The markdownify filter requires use of Nunjuck's safe filter to output - so make sure you trust the string being markdownified.

Credit where credit is due, this idea was completely pinched from Hugo's markdownify function.

addattribute

Takes a string or a markSafe object, and adds an attribute or property to it.

{{ 'This is some text' | addattribute('lang', 'en') }} // <span lang="en">This is some text</span>

Could also be set up to add a specific attribute - for example, rel:

env.addFilter('addrel', (element, content) => addattribute({
  element,
  attribute: 'rel',
  content,
}))

could then be used

{{ '<a href="https://example.com/next-article/">Next article</a>' | addrel('next') }} // <a href="https://example.com/next-article/" rel="next">Next article</a>

Set up

Requires Node 14.x and npm 6.x.

Installation

First install this as a dependency in your project:

npm install @injms/quack-nunjucks-filters

Using in Nunjucks

const nunjucks = require('nunjucks')

const {
  cssmin,
  debug,
  humandate,
  isodate,
  markdownify,
} = require('@injms/quack-nunjucks-filters')

const env = new nunjucks.Environment()

env.addFilter('cssmin', (css) => cssmin(css))
env.addFilter('debug', (thing) => debug(thing))
env.addFilter('humandate', (datestring, locale) => humandate(datestring, locale))
env.addFilter('isodate', (datestring) => isodate(datestring))
env.addFilter('markdownify', (markdown) => markdownify.render(markdown)) // Note the use of `render()`

And now you can use these filters wherever you use env to render markup; for example:

env.renderString('<time datetime="{{ date | isodate }}">{{ date | humandate('en-AU') }}</time>', { date: 1592942878800 })

gives:

<time datetime="2020-06-23T20:07:58.800Z">23 July 2020</time>

Using with Eleventy

Import the filters into the .eleventy.js file:

// .eleventy.js

const {
  cssmin,
  debug,
  humandate,
  isodate,
  markdownify,
} = require('@injms/quack-nunjucks-filters')

module.exports = (eleventyConfig) => {
  eleventyConfig.addFilter('cssmin', (css) => cssmin(css))
  eleventyConfig.addFilter('debug', (thing) => debug(thing))
  eleventyConfig.addFilter('humandate', (datestring, locale) => humandate(datestring, locale))
  eleventyConfig.addFilter('isodate', (datestring) => isodate(datestring))
  eleventyConfig.addFilter('markdownify', (markdown) => markdownify.render(markdown)) // Note the use of `render()`

  // rest of Eleventy's config and setup
}

Now these can be used in the template:

<!-- blog-post.njk -->

<h2>{{ blog_post_title }}</h2>
<time datetime="{{ publish_time | isodate }}">
  {{ publish_time | humandate }}
</time>

<h3>Author</h3>
{{ author_biography | markdownify }}

🧪 Testing

Clone the repo; run npm install; and then run npm test will run all the tests.

Tests use Mocha, Chai, and Sinon.

👔 Linting

npm run lint will lint all the JavaScript files.

This is linted using a slightly extended version of standard. The only adjustment is that trailing commas - comma-dangle - are allowed to give a better diff.

🐞 Bugs and issues

Make sure to check the issues page before raising a new issue please - ta!