Gordon Delfel's Blog

Setting up Pug + Gulp

Setting up Pug + Gulp

Gordon Delfel's photo
Gordon Delfel
·

5 min read

Overview

Creating a website is easy enough using basic HTML, CSS, and Javascript. We will be creating a boilerplate using a Pug and Gulp which will make it much easier to make changes on a website with multiple pages.

A couple of assumptions:

  • You have worked with HTML, CSS, and Javascript in the past.
  • You already have NodeJS installed, as well as the Node Package Manager (NPM)
  • You know how to access and use a terminal

Pug

What happens when you have multiple pages, but they all re-use the same <head></head> code, or a nav bar? That's where Pug comes in. Pug is a templating language that replaces HTML in your code base. With a file named head.pug containing everything from our <head></head> element, we can include it in other pug files using the following code: include path/to/file.pug.

What that means is no more retyping the same code on every single page. No more will you need to change every page when you decide to change the nav element.

Ultimately, Pug compiles into HTML. That's where Gulp comes in.

Gulp

Gulp helps automate your workflow. I know that sounds vague, and it is, so let's stay focused on how we will use Gulp.

Gulp lets you write javascript files that perform tasks on your code. In our case, we are going to use it to automatically convert our .pug files into .html files and place them in a folder named dist.

Packages and Folders

Create a new folder. My folder is called Gulp_Pug, but yours can be whatever you like.

Lets intialize NPM. This will get your folder ready for installing packages. Open a terminal and navigate to the folder you just created and type the following

npm init

Next we need to install gulp, pug, and an additional module called gulp-pug that allows the two to work together. In the same terminal, enter the following:

npm install --save-dev gulp pug gulp-pug

Now we need to create a few files and folders. Don't worry about adding anything to these yet, and keep in mind some of these should already be created Your folders and files should look like this:

Gulp_Pug/
┣ node_modules/ -- contains pug, gulp, gulp-pug and dependencies
┣ dist/ -- will hold our final .html files
┣ templates/ -- holds our .pug files
┃ ┣ includes/ -- holds .pug files we will include in pages
┃ ┃ ┗ head.pug -- holds the <head> element
┃ ┗ index.pug -- what will be our main html page
┣ gulpfile.js -- will hold a gulp task to convert .pug files
┣ package-lock.json -- created with npm init
┗ package.json -- created with npm init

Pug

Lets get started with Pug templates. In this tutorial you'll be doing a lot of copying and pasting, but I encourage you to learn more about Pug and it's syntax here. Then you'll be able to expand on this boilerplate!

Open /templates/index.pug in your code editor of choice and paste in the following code:

doctype html
head
  meta(charset='utf-8')
  title HTML5 Template
  meta(name='description' content='HTML5 Template')
  meta(name='author' content='Website')
p Hello world!

All I did to get this code was grab a basic HTML5 template and convert it using an online HTML to PUG converter. I recommend keeping this around as it can be pretty useful for converting small snippets of HTML.

Notice how the head is included in index.pug? We're going to be using this all over the website, so lets turn it into an include. Copy the head section from the code you just pasted. Now open /templates/includes/head.pug and paste in the head section:

head
  meta(charset='utf-8')
  title HTML5 Template
  meta(name='description' content='HTML5 Template')
  meta(name='author' content='Website')

Go back to index.pug and replace the head section with include includes/head.pug:

doctype html
include includes/head.pug
p Hello world!

So how does any of this turn into an HTML page you can actually look at? That's where Gulp comes in.

Gulp

Now we get down to creating a Gulp task that will search your /templates folder for .pug files and automatically convert them to HTML before placing them in /dist.

Open your gulpfile.js and paste the following code:

var gulp = require('gulp'),
    pug = require('gulp-pug');

gulp.task('build', function() {
    return gulp.src('./templates/*.pug')
        .pipe(pug())
        .pipe(gulp.dest('./dist'));
});

This may look confusing, but essentially all that is happening here is:

  1. Gulp is creating a task called build that can be ran in the terminal with gulp build
  2. Gulp searches the ./templates directory for anything ending in .pug. If you're unfamiliar with the wildcard character * I recommend reading more here.
  3. Gulp then runs the file through gulp-pug (defined as pug) and places the HTML output into the ./dist folder.

Lets run it! Open your terminal again and type gulp build. If all goes well, you should see something like:

[16:03:20] Starting 'build'...
[16:03:20] Finished 'build' after 42 ms

Now you should find index.html inside your /dist folder. Feel free to open it and play around at this point. You have a functional boilerplate!

GulpWeb Development