# Setting up Pug + Gulp

## 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](https://pugjs.org/api/getting-started.html)  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](https://gulpjs.com/)  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:
```text
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.](https://pugjs.org/api/getting-started.html) 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](https://html-to-pug.com/) 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:
```javascript
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.](https://gulpjs.com/docs/en/getting-started/explaining-globs/) 
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!