8,482 reads

An Introduction to PUG

by Timothy RobardsDecember 19th, 2018

Too Long; Didn't Read

Pug (formerly known as Jade) is a preprocessor which simplifies the task of writing <a href="https://hackernoon.com/tagged/html" target="_blank">HTML</a>. It also adds a ton of functionality, such as <a href="https://hackernoon.com/tagged/javascript" target="_blank">Javascript</a> objects, conditionals, loops, mixins and templates. The syntax is arguably a lot cleaner to read and it can be a real time-saver when working with a lot of HTML (especially frameworks such as Bootstrap, Foundation, etc).

Companies Mentioned

Pug (formerly known as Jade) is a preprocessor which simplifies the task of writing HTML. It also adds a ton of functionality, such as Javascript objects, conditionals, loops, mixins and templates. The syntax is arguably a lot cleaner to read and it can be a real time-saver when working with a lot of HTML (especially frameworks such as Bootstrap, Foundation, etc).

Lets take a peek at some Pug syntax & compare it to regular HTML..

// index.pug

doctype html  html(lang='en')   head   title Pug demo body   h1 Welcome to Pug Life   div.container     p I'm a p that needs to be contained!

Note the use of indentation to nest our HTML as we require. And the lack of closing tags!

And here’s the standard HTML output:

// index.html

<!DOCTYPE html>  <html lang="en">   <head>   <title>Pug demo</title> </head> <body>   <h1>Welcome to Pug Life</h1>   <div class="container">     <p>I'm a p that needs to be contained!</p>   </div> </body></html>

By comparison our pug code is much more concise. Additionally, the compiler will throw errors if we have any mistakes in our code – which makes for convenient error prevention.

So let’s get started!

How to install Pug

Note: You’ll need NodeJS installed! Go ahead and install if you haven’t already.

To install pug run the following command from your terminal:

npm install -g pug-cli

We install globally with -g as we’ll need access to Pug commands from terminal.

Now in our root directory, create a file called index.pug.

Lets test this out! Add the following text to our file as follows:

// file: index.pug

doctype html

And lets compile it to HTML with the following command:

pug index.pug

We should now see our index.html generated in the root directory. It will of course convert to HTML as follows:

// file: index.html

<!DOCTYPE html>

When working on a larger project, you might want to use a more specific compile command, such as:

pug -w ./ -o ./html -P

The -w flag will watch our pug file for changes and re-compile automatically each time we save. ./ will watch everything in the current directory. -o ./html will set the output folder to html. -P will make our HTML source code pretty printed, with indentation, line-breaks, etc.

Note: Once you’ve executed this command, keep your terminal running to continue the auto-compile!

The Basics

Lets get started on a basic HTML structure. Type up the following in your index.pug.

doctype htmlhtmlheadbodyh1#title Lets get pugging!p I'm a paragraphp.I'm a multi-line paragraph!And this is the second line.p.para.This paragraph has class!.firstDiv A div with a class.#secondDiv A div with an id.

Note the use of indentation! Make sure you tab your child elements.

When you save and open up index.html.You’ll see the complete HTML generated like so..

<!DOCTYPE html><html><head></head><body><h1 id="title">Lets get pugging!</h1><p>I'm a paragraph</p><p>I'm a multi-line paragraph!And this is the second line.</p><p class="para">This paragraph has class!</p><div class="firstDiv">A div with a class.</div><div id="secondDiv">A div with an id.</div></body></html>

Attributes

Lets take a look some syntax for setting attributes in pug.

doctype htmlhtmlhead//- Invisible comment.//Visible comment.

script(src="script.js")  
link(rel='stylesheet', href='css/main.css')

bodya(href="https://google.com") google.com

img(src="https://google.com/logo.png" alt="google logo")

input(type="password" name ="inputpass")  
input(type='checkbox' checked)  
input(type='checkbox' checked=true)  
input(type='checkbox' checked=false)

//Inline styles  
a(href="your-link", style={color: "Red", "font-size": "24px"}) I'm a link!

Our HTML will generate as follows:

<!DOCTYPE html><html><head><script src="script.js"></script><link rel="stylesheet" href="css/main.css"></head>

<body><a href="https://google.com">google.com</a><img src="https://google.com/logo.png" alt="google logo">

<input type="password" name="inputpass">  
<input type="checkbox" checked>  
<input type="checkbox" checked>  
<input type="checkbox">

<!--Inline styles-->  
<a href="your-link" style="color:Red;font-size:24px;">I'm a  link!</a>

</body></html>

Adding JavaScript

One of the most powerful features of Pug, is the ability to easily make our HTML dynamic, using inline JavaScript. Lets take a look at a few examples:

Variables

- let name = 'Timothy'- let city = 'Montreal'- let transport = { type: 'Bike' }- let food = ['Tacos', 'Pizza', 'Cheetos']

// Incrementation for numeric variablesage++

// Assigning variables to elementsp= name span.age= age

Interpolation

- let size ="medium"img(src=`https://google.com/logo-${size}.png` alt="logo")

---------------------// output:

Loops

uleach city in ['Sydney', 'Montreal', 'New York']li= city

uleach city, index in ['Sydney', 'Montreal', 'New York']li= 'Number ' + index + ': ' + city

-------------------------------------------------// output:

<ul><li>Sydney</li><li>Montreal</li><li>New York</li></ul>

<ul><li>Number 0: Sydney</li><li>Number 1: Montreal</li><li>Number 2: New York</li></ul>

Conditionals

if user  h2 Welcome back #{user}!else if admin  h2 Hey #{admin}!else  h2 Sign up!

Mixins

// Declarationmixin listulli Sydneyli Montrealli New York

// Use_+_list_+_list

------------------// output:

<ul><li>Sydney</li><li>Montreal</li><li>New York</li></ul>

Mixins compile as functions, and therefore can take arguments!

mixin city(name)li.city= nameul+city('Sydney')+city('Montreal')+city('New York')

--------------------// output:

<ul><li class="city">Sydney</li><li class="city">Montreal</li><li class="city">New York</li></ul>

The features we’ve looked at here are really just the tip of the iceberg! For the full specs check out PugJS.org — Getting Started.

Structuring your Pug files

A well organized template system is a crucial part of any development process. What follows is a look at how we can organize our projects using both includes and extends.

Includes

Includes allow you to insert the contents of one Pug file into another. All you need to do is add an include directive into your main pug file, as follows:

doctype htmlhtmlinclude additions.pugbodyh1 My Headingp Here goes the text.

Lets now create the additions.pug file and add the following content:

headtitle My Sitescript(src='/js/jquery.js')script(src='/js/app.js')

Our files will compile merged into index.html like so:

<!DOCTYPE html><html><head><title>My Site</title><script src="/js/jquery.js"></script><script src="/js/app.js"></script></head><body><h1>My Heading</h1><p>Here goes the text.</p></body></html>

Extends

The extends keyword allows a template to extend a layout or parent template. It can then override certain pre-defined blocks of content, using the block command.

We want to keep our projects as organised as possible! A logical template system will define a base template, and then all the other templates extend from it. For example:

// file: index.pug

extends layout.pug

block contenth1 hello world!

Here we’ve set our index.pug file as the base template. With a call to the layout.pug file via extends.

Note the use of the block command. This is how we direct part of a template to be extended.

// file: layout.pug

doctype htmlhtml(lang="en")headmeta(charset='utf-8')bodyblock contenth2 hello again world!

Here is the content of our layout.pug, we use the block command with the same name (you can call it whatever you like!), so the pug engine knows where to put the code block.

This code will compile as follows:

<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"></head><body><h1>hello world!</h1><h2>hello again world!</h2></body></html>

Of course you can use as many blocks as you like, and create as many pug files as you like. The point is to build a logical structure into our projects & keep our code clean and organised!

Conclusion

And that’s it! We’ve setup a Pug development environment and covered the fundamentals. We’ve looked at many of the features provided by adding JavaScript such as variables, interpolation, loops, conditionals and mixins. We’ve also looked at how to structure our Pug files using templating with the include and extend directives.

I hope you found this article useful! You can follow me on Medium. I’m also on Twitter. Feel free to leave any questions in the comments below. I’ll be glad to help out!