Nonchalant Programming Master

    njk

    4.2.0 • Public • Published

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

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

    Install

    npm i njk

    DownloadsWeekly Downloads

    44

    Version

    4.2.0

    License

    MIT

    Unpacked Size

    43.6 kB

    Total Files

    43

    Last publish

    Collaborators

    • mohitsingh