Handle HTML includes with Jade

As a front end developer I’m sometimes confront to projects where I need to deal with only static HTML files. Being able to use inclusions in PHP makes it so much easier to maintain.

I’m a Git fan and I usually use Github as remote repository, it allows the creation of a gh-page branch. Basically it means you can have a static web page for your Github project for free. Really it’s easy here’s the Github doc.

Github pages are awesome but it’s then impossible to use php includes in them…

What’s Jade

So let’s see how Jade can help.

Jade is a template engine build for NodeJS heavily inspired by HAML (the Ruby on Rails template engine). You can play around with Jade’s interactive doc.

Obviously it’s an easy way to write HTML, there’s less characters to type, indentation and spaces actually means something and at the end you need to compile it from Jade to HTML. If you’re familiar to Sass or CoffeeScript, well Jade will be easy for you.

The coolest thing in Jade (for me) is the possibility to handle includes. It works exactly the same as in PHP and this cool feature doesn’t seems to exists in HAML or in Slim (another template engine that compiles to HTML).

How to include

Let’s say you have a home.jade file (which could be your default template) and you have another jade file which is navbar.jade then here’s how to include it into your home.jade file:

doctype 5
html(lang="en")
  head
    meta(charset="utf-8")
    title my awesome web app
    link(rel="stylesheet", href="style.css")
    //if lt IE 9 
      script(src="js/libs/html5shiv.js")
  body
    include ./path/to/navbar

Compile it to HTML and you’re done!

How to install

Ok but of course you’ll need to first install NodeJS + NPM and when you’re done just install Jade like this:

sudo npm install -g jade

The -g flag means it will install Jade globally on you system.

How to compile

Compiling is achieved by the command line :

jade -P *.jade --out ./path/to/html/dir

The -P flag stands for “pretty”, for what I can see the compiled HTML gets out minified by default, and this flag renders it like regular HTML.

The binary doesn’t have a watch option (like in Sass or Compass) but it’s possible to achieve this with Grunt or Make or what ever you want.

As a side note be aware that Jade becomes really impressive when used with express.js (the NodeJS framework).

CodeKit is a front-end powerfull tool

Be also aware that there’s an awesome app for Mac users called CodeKit. You can automates tones of task in tones of differents languages. CoffeeScript, LESS, SASS/SCSS, Jade, Slim, HAML, JS min/lint/concat, etc… I love this tool, the developer‘s release notes are hilarious 😛 and the latest update includes a “Codekit way” for handling html includes which is nice.