Njk NPM | npm.io

About

njk is in maintenance mode. It was created more than four years ago to help me migrate from Jekyll. It served it's purpose very well but since then, I've migrated almost all of my sites to use other tools and I no longer use njk. I've added tests to make sure deps upgrade don't render it useless.

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.

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>

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>

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).

cli nunjucks markdown front-matter html template templating render

chalk chalk-template chokidar commander data-dir fs-extra globby gray-matter html-minifier lodash.merge log-symbols marked marked-gfm-heading-id marked-mangle nunjucks prefer-local

@mohitsingh/static @infinitebrahmanuniverse/nolb-nj @everything-registry/sub-chunk-2294 @zalastax/nolb-nj

2 years ago

3 years ago

3 years ago

3 years ago

3 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

4 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

6 years ago

6 years ago

6 years ago

6 years ago

6 years ago

6 years ago

7 years ago

7 years ago

7 years ago

7 years ago

7 years ago

7 years ago

7 years ago

7 years ago

7 years ago

7 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago

8 years ago