Now Entering Pugspace

a super entranced pug

You've entered a world unlike your own. A world where pugs roam free and HTML can be written like the snip snappy sharp human you are. That extremely parallel world, so close to our own, is called pug.js (formally known as jade). Let's dig in to this new world and go over the basic features that formulate such a wonderful place.

Let's get you Started

The best place to prototype pug is none other than Codepen! Create a new little play pen for your pug to bounce around in and then change the HTML preprocessor to jade:

jade setup screen

Lemme Write Some Markup

a little pug powering stepping

If you're new to pug, don't be scared! It's pretty quick to pick up and incredibly flexible. We'll start with a simple topic component in HTML.

  <div class="topic-component">
  <a href="#">Link</a>

Nothing to see here, we all know this markup from a mile away (Did you know pugs can see in x-ray vision?). What if we took this markup and pugified it:

  h4 Title
  p Description
  a(href="#") Link

Now we're cooking! We stripped out all this HTML stuff and we're left some pretty pug looking stuff. Let's break down what went on here:

Pug takes out all those closing brackets in favor of indentation:

  <div class="topic-component">
  <a href="">Link

You don't even need those pesky brackets at all in pug:

  div class="topic-component"
  h4 Title
  p Description
  a href="#"

We used dots in our css for a class, yea? Pug too!:

  h4 Title
  p Description
  a href="#"

Shoot, who needs div anyway. Make sure to snuggly wrap those attributes like href up too:

  h4 Title
  p Description

With that we have a complete pug component, full of all the syntactical warmness you could ever want in pug. The result here will be the exact same as our original HTML component. It's pretty darn quick to write too.

A Litter of Variables

a goofy guy going up to a bunch of happy pugs

You're all set with learning pug's condensed syntax, now let's get into some more complex features. Variables are handy little buggers which let you store values and reuse them later on. This is really useful for stuff like your page title. Let's make a little litter of variables for our pug named Fluffy:

  - var pageTitle = "Fluffy"
- var pageCaption = "A cute pug for you"

In pug we use - var to declare a variable, and = to assign a value. To reference those variables, we can use interpolation - a way to tell pug that the following text is actually a variable (Shoot, why not call it the pugstache). This will take our strings "Fluffy" and "A cute pug for you" and place them inside our markup:

  h1 #{pageTitle} 
p #{pageCaption}

The Ultimate Mixin

Another pug powerhouse feature is the mixin. If you're familiar with SASS, the same concept applies here. A mixin takes in a set of arguments and then runs through some markup. How about we make an image mixin for Fluffy:

  mixin image(name, caption)
    img(src=name + ".jpg")
    figcaption= caption

We used the keyword mixin to create a mixin named image that passes in a comma separated list of 2 arguments, name and caption. We also didn't use interpolation here when using the our variables. How come? The best way to use interpolation is when you want to place plain text before or after your variables. However, you can also treat passing in a variable like you would in javascript - an element = your variable + something else. This is known as concatenation.

To use our new mixin, all we have to do is use + then our mixin name, image:

  +image("fluffy", "Fluffy with his cute friend")

Shimmy up a Template

a pug going on an adventure

I bet you've written a template many many many times as a developer, then copied that template for each page. Well let's embark on a new journey, outside of codepen, in the wonders of template inheritance. This feature allows you to create a page by calling a template then injecting content into that template. Forget about copying the template over and over again!

Let's create a base template, named after our fantastic friend, called fluffy.pug:

    //- fluffy.pug
      //- Fluffy's head
      block content

I snuck a little something into fluffy here called a block. We'll learn more about blocks soon! Let's start by making a coat.pug page to show off Fluffy's nice coat:

    //- coat.pug
  //- Extend a template given a file path to that template
  extend fluffy.pug

All that markup from our fluffy.pug template is now copied into coat.pug. You don't have to rewrite the template for every page, just extend it, using the path to our template, with pug. Sweet, right!

Ayo, Mr. Block!

Remember that block we had on fluffy.pug? A block is a bank we use to store content into later on. Let's use that block to add in some content to coat.pug:

    //- coat.pug
  extend fluffy.pug

  block content
    h2 Fluffy's Sexy Coat
    p His coat brings all the little pugs to the yard. Dazzling, radiant, you name it, Fluffys' got it.
    a(href="") Check Fluffy out on Okcupid ;)

The same place we added that block in fluffy.pug will be the exact place it shows up in coat.pug - right inside the body. It's almost time to run with the pugs!

Reuse some Partials

a big lazy pug

You've gone pretty deep in pug space and you've almost explored all the basics! One last feature we'll cover here is called include. An include is a way to reuse components. That blurb we used earlier is a prime use case for include. What if we wanted to show off a blurb of Fluffy's sexy coat on more than one page? First we gotta make that little blurb has its own file called coat-blurb.pug:

    //- coat-blurb.pug
  h2 Fluffy's Sexy Coat
  p His coat brings all the little pugs to the yard. Dazzling, radiant, you name it, Fluffys' got it.
  a(href="") Check Fluffy out on Okcupid ;)

Back in our coat.pug let's strip out that blurb and add in an include:

    //- coat.pug
  extend fluffy.pug

  block content
    //- Include a partial given the file path to that partial
    include coat-blurb.pug

Lookin pretty clean, eh! We're still extending fluffy.pug and we're still passing in some content to our block. The only difference here is we're including our coat blurb rather than writing it again by hand. I'm sure Fluffy would want all his admirers to see that coat blurb on his bulky-legs.pug page too!


a bunch of happy pugs around a goofy guy

Over the course of this post you've learned quite a lot! You've learned how to:

There's much more to learn in the world of pug and with that statement I leave you with three resources. One, your first and foremost go to resource for everything pug, the pug website. Two, a handy little pug boilerplate for ya that's part of my static site generator called Mimogear. Three, a rockin pug cheat sheet. Use them wisely and fulfill your destiny as pug master!

I wish you the best as you begin to learn pug, my fellow Codepen friends!