michael le

Static Site Generator Tutorial Part 2: Nunjucks and Templates

Mike -

In Part 1, we set up gulpjs and browser-sync to build a static site generator.
In this part, we will set up a template engine called Nunjucks and set up a base template.

Installing Plugins

Let’s start by installing the plugins in our project. In our command line, type the following.

$ npm install --save-dev gulp-nunjucks-render

About Nunjucks

Nunjucks allows us to break our html into smaller reusable pieces that we can use in other html files. We can even inject data to populate our html files. If you have used Flask, you’ll notice the markup is inspired by Jinja2.

Creating a Template

We’ll copy our app/index.html file to app/templates/base.html.
Then, we’ll make a pages directory and move the index.html to app/pages/index.html

$ cp app/index.html app/templates/base.html
$ mv app/index.html app/pages/index.html

  Folder Structure
├── app
│   └── templates
│       └── base.html
|   └── pages
│       └── index.html
├── gulpfile.js

We’ll change the markup for base.html to become a Nunjucks template.

<!-- base.html -->
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <title>
      {% block title %} {% endblock %} <!-- we'll change the title -->
    </title>

    <!-- Bootstrap -->
    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/css/bootstrap.min.css">
  </head>

  <body>

    <div class="container container-fluid">
      {% block content %} <!--- Our content will be here -->
      {% endblock %}
    </div>

    <!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
    <script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min.js"></script>
    <!-- Include all compiled plugins (below), or include individual files as needed -->
    <!-- Latest compiled and minified JavaScript -->
    <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.6/js/bootstrap.min.js"></script>
  </body>
</html>

Let’s change the index.html to take advantage of our new base.html nunjucks template.

<!-- index.html -->
{% extends "base.html" %} <!-- we're extending the base template -->

{% block title %}This is the new title of our webpage{% endblock %}

{% block content %}
<h1>Hello<h1>
<p>
  We just extended the base template. Anything we put in the content blocks will
  be specific to the index.html page.
</p>
{% endblock %}

Integrating Gulpjs and Nunjucks

Now that we have our template and pages file ready.
We’ll import the plugin and write a gulp task for it

// gulpfile.js
var gulp              = require('gulp');
var browserSync       = require('browser-sync');
var nunjucksRender 		= require('gulp-nunjucks-render'); // importing the plugin

gulp.task('serve', function() {
    console.log('running server');
    browserSync({
        server: {
            baseDir: 'app'
        }
    });
});

// writing up the gulp nunjucks task
gulp.task('nunjucks', function() {
  console.log('nunjucking');

  // configuring the templates folder for nunjucks
  nunjucksRender.nunjucks.configure(['app/templates/']);

  // get the pages files
  return gulp.src('app/pages/**/*.+(html)')
    .pipe(nunjucksRender())
    .pipe(gulp.dest('app'))
});

//default task to be run with gulp
gulp.task('default', ['serve']);

Running Nunjucks

Now, we can run the nunjucks task and then the serve task to see our changes.

$ gulp nunjucks
$ gulp serve

Results

Nunjucks took our base template and index file and turned it into a fully compiled html page.
We can make as many pages files as we want and the nunjucks task will compile them into static files.
We can combine the nunjucks and serve commands as another task, but we’ll save it for another tutorial.
You can check out our changes on Github.