/njk

Render nunjucks templates with markdown and front-matter

Primary LanguageJavaScriptMIT LicenseMIT

njk

GitHub Workflow Status npm version node-current GitHub

Render nunjucks templates with markdown and front-matter
generate ( and minify ) html based on nunjucks templates, markdown, front-matter and json/yml data


About

njk is no longer maintained. It was created in 2017 as a command line tool to help me migrate from Jekyll. It served it's purpose well for me, but since then, I've migrated almost all of my sites to use other tools. And for all those repositories using it as a library along with nunjucks and express, 🫡

Install

Install with npm

npm install --dev njk

or with yarn

yarn add --dev njk

Usage

njk <files|dirs|globs> [options]

Command Line Flags

  • -V prints version
  • -h or --help prints help text
  • -v or --verbose includes additional logging
  • -b or --block wraps a content block by default. This is convenient when you you want to extend just one block. This helps you avoid writing extends tag in child template
  • -c or --clean uses clean urls (urls with forward slash) for output files.
  • -q or --quiet silences the output until any error occurs.
  • -w or --watch runs everything in watch mode. HTML is not minified in this mode.

Command Line Options

  • -d or --data pass either json file path of yaml directory path containing data.
  • -t or --template pass template directories (nunjucks searchPaths). Multiple template directories can be passed, separated by comma ,
  • -o or --out pass output directory

File Specific Options

Following options can be configured through front-matter of individual files.

  • layout parent layout/template to use for rendering a file. This inserts a extends tag automatically.
  • block Wraps a content block around a page. If enabled, an empty content block is required in parent template where content will be inserted.
  • clean Uses clean urls while writing files. For example file.html will be written as file/index.html

Contributing

You can help improving njk in following ways -

  • Found a bug, create an issue with relevant information.
  • Want a feature to be added, A pull request is always welcome.

Some Examples

1. Rendering a template using block flag and layout option in front matter

We can avoid wrapping extends tags and overriding block tags, If we need to inject single block in parent template.

Step 1

Consider we have a nunjucks template with single block.

default.njk

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Page Title</title>
</head>
<body>
  {% block content %}{% endblock %}
  <!-- The block name content is important -->
</body>
</html>

and a simple html page

index.html

---
layout: default
---
<header>
<h1>On Laughing</h1>
</header>
<main>
<p>A laugh draws a lot of painful lines.</p>
</main>
<footer>
<small>Copyright &copy; Creator Inc.</small>
</footer>

Step 2

Now, Let's run njk.

njk index.html -b

The current directory will be used for templates.

Result

The result will be something like

dist/index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Page Title</title>
  </head>
  <body>
    <header>
      <h1>On Laughing</h1>
    </header>
    <main>
      <p>A laugh draws a lot of painful lines.</p>
    </main>
    <footer>
      <small>Copyright © Creator Inc.</small>
    </footer>
  </body>
</html>
2. Rendering a template using layout option in front matter

Wrapping extends tag in each of our file isn't super cool,

and we can avoid this by using layout option in front-matter.

Example

Step 1

Consider we have a nunjucks template with 3 blocks.

default.njk

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Page Title</title>
</head>
<body>
  <header>
    {% block header %}{% endblock %}
  </header>
  <main>
    {% block main %}{% endblock %}
  </main>
  <footer>
    {% block footer %}{% endblock %}
  </footer>
</body>
</html>

and a simple html page with content for these 3 blocks

index.html

---
layout: default
---
{% block header %}
<h1>On Laughing</h1>
{% endblock %}
{% block main %}
<p>A laugh draws a lot of painful lines.</p>
{% endblock %}
{% block footer %}
<small>Copyright &copy; Creator Inc.</small>
{% endblock %}

Step 2

Now, Let's run njk.

njk index.html

The current directory will be used for templates.

Result

The result will be something like

dist/index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Page Title</title>
  </head>
  <body>
    <header><h1>On Laughing</h1></header>
    <main><p>A laugh draws a lot of painful lines.</p></main>
    <footer><small>Copyright © Creator Inc.</small></footer>
  </body>
</html>
Extra : Configuring layout through data passed

We can go one step further and configure layout it in the data passed with -d or --data

Step 1

Remove front-matter from index.html

index.html

{% block header %}
<h1>On Laughing</h1>
{% endblock %}
{% block main %}
<p>A laugh draws a lot of painful lines.</p>
{% endblock %}
{% block footer %}
<small>Copyright &copy; Creator Inc.</small>
{% endblock %}

Step 2 ( using yml )

data/page.yml

layout: default

We need to run

njk index.html -d data

Note that file name is important here, as we need page.layout property.

Step 2 ( using json )

We can pass a single json file instead of data folder

data.json

{
  "page": {
    "layout": "default"
  }
}

We need to run

njk index.html -d data.json

Result

The result will be same as our previous run (Example 2).