Pug.js is a HTML templating engine, which means you can write much simpler Pug code, which Pug compiler will compile into HTML code, that browser can understand. But why not write HTML code in the first place?

Pug has powerful features like conditions, loops, includes, mixins using which we can render HTML code based on user input or reference data. Pug also support JavaScript natively, hence using JavaScript expressions, we can format HTML code.

An application of that would be Email Templates to send email customized to particular user. We can make an email template using Pug with variables that can be changed based on user to whom we are sending that email. Before sending email,we can compile Pug to HTML code with user data to fill the gaps where that dynamic information should go. Trust me, this will save you lot of time.

There are lot of applications where HTML code needs to be generated on server or browser and Pug fits perfectly for those kind of environments. So let’s get started.

Pug.js, as from its name is a JavaScript library. Hence, we can run it inside browser or on node.js. Here, I am using node.js to demonstrate few examples.

Pug provides two npm packages viz. pug and pug-cli . pug is a general purpose package and pug-cli are command line interface to compile pug code into HTML code from command line without writing any JavaScript code. I am going to start with pug-cli because this is very easy to do.

Hence, let’s install pug-cli package with command npm install -g pug-cli , -g because we need to install it globally as to access Pug commands from command prompt or terminal. Pug files ends with extension .pug and compiles to files with extension .html

If you have index.pug file in a folder, you can open terminal there and execute command pug index.pug which should compile index.pug into index.html file. If you have a separate folder for all .pug files, let’s say src then you should use pug src command which should place all compiled .html files in the same folder. I like all compiled files to be located in separate folder, like dist . Hence I used pug src --pretty --out dist command. You can visit repo page on GitHub at https://github.com/pugjs/pug-cli to know more about pug CLI command flags.

Let’s see how pug code looks like.

(source)

As you can see from above, for the beginner it doesn’t make any sense. But give me a chance to walk you through it. doctype html is a syntax which Pug compiles to <!DOCTYPE html> and html , head and body are regular tags which compiled to <html></html> , <head></head> and <body></body> . Like python, Pug uses tabs to make code blocks. Hence as head and body tags are inside html tabbed block, they will be included in html tag, while head and body will be siblings. Please read the code and comments carefully from here on, because most of the stuff is explained inside the code itself in form of comments.

When you will compile above code, it will look like

(output)

Take few moments to understand how it happened, because after this, everything is pretty simple.

HTML code is mostly about tags, attributes and text. Hence Pug mostly focuses on that, making is injectable with dynamic data. Let’s see how tags and text works. Pug uses same HTML tags so no worry there.

(source)

(output)

Writing attributes in Pug can be little bit tricky. But I am sure, it won’t be too hard to understand after reading comments.

(source)

From here on, I am formatting the code little bit so that you can compare Pug code with HTML.

(output)

The powerful thing about Pug is inline JavaScript code. This is where dynamic data comes from. Binding this dynamic data to HTML can be tricky using custom approach, but with Pug, it’s kind of no brainier.

(source)

If you are familiar with Angular or React, then this must not make you crazy.

(output)

You mostly won’t hardcode data in the Pug code. This data is mostly dynamic and can come from any source, like SQL Database or REST api. We will learn about how to inject data into Pug template in upcoming topic once we are done with all features of Pug.

If you are used to PHP, then you must know that we can include other PHP files into the code. Pug also support including code from other Pug and non Pug files.

(source)

(includes)

(output)

If you are wondering what if I need to use same piece of code over and over again, then don’t worry. If you are familiar with SASS, then you must know about mixin. Pug also provide similar kind of feature to add code re-usability in your program. Mixin in Pug is wrapper or functional wrapper around a block of Pug code.

(source)

(output)

You probably want to define mixins in separate file and include them in the file when needed to make them truly resuable.