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><!--Visible comment.--><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:
<img src="https://google.com/logo-medium.png" alt="logo">
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>
<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!