SUPER SIMPLE Static Site Generation with Node, Jade, Gulp and JSON

Check out the code on github (Setup directions below)

Static Site? But…why?

If you are asking this question, do yourself a favor and skim through the free O’Reilly book Static Site Generators: Modern Tools for Static Website Development.

The quick answer is because you can have a static website and still have all the bells and whistles.

The slightly longer answer is a static website will perform well, can be hosted anywhere, is secure and can easily be version controlled. And with the current depth of javascript APIs you can pretty much have any feature you want for basic websites. For more on these points, read the book mentioned above.

What I didn’t realize until I noticed an email from O’Reilly about the book, is that I’m already using the concepts of Static Site Generators, except without the Generator part. I recently rebuilt my employer’s website using Gulp.js, Jade templates and JSON. It is a homepage with some case study pages. I wanted to learn Jade because I’m also dabbling in Express.js and html pages fulfilled the requirements of the project. Piping the data into Jade was something I had to work hard to understand, so hopefully this helps someone else.

Check out the code on github

The Goal.

So after reading the book, I thought it would helpful for other developers to see my approach. All the generators are cool, but I found it easy enough to produce a full website just using the tools I use everyday. And building it myself is always more rewarding. To-do MVC is our usual ‘Hello World!’ , but to me a good sample of a static website would be more comparable to a simple WordPress website. After all, WordPress is at least 25% of all websites on the web!

So what is appealing about the basic WordPress site that we often build for our small clients and projects? I thought it was the stuff you get right out of the box with WP’s core default themes:

  1. Theming/Templates (header, footer, shared markup)
  2. Easy page generation
  3. Easy post generation
  4. Easy to get a post loop in a page (via the loop)
  5. Sorting posts by categories (via the loop)

So the approach I took was building a new portfolio website. It has all toe stuff you’d see in most basic websites. Which would lead to the following pages:

  1. Home => index.html
  2. About Me => about.html
  3. Resume => resume.html
  4. Contact Me => contact.html (this is where you could use a service for the form, or AJAX the POST info, or whatever the cool kids are doing nowadays)
  5. Blog => blog/index.html which loops over all blog posts and provides a post summary
  6. Blog Pages => blog/[PAGE NAME].html
  7. Blog Categories => blog/category-[CATEGORY NAME].html
  8. Assets => public/ just a home for images, css, js

The Core Tools.

Ok, if you aren’t slightly familiar with these tools, check them out and double back. I’m going to jump right in.

  1. Node.js: node serves as the server and the engine in the build process
  2. Gulp.js: the task manager
  3. Jade Templates (gulp-jade): the templating system
  4. JSON: serves as our database

The build.

I have a personal preference that I don’t like gulp and node messing up my root folder, so I like to tuck the gulp build into a _src directory. That ends up leaving all the html and assets in the root like a good old fashioned website.

So I’ll start by breaking down what is in there.

Three collections of data are mentioned but are not JSON files.

  1. ‘sections’ is an array called ‘websiteLinks’ that is in the gulpfile.js
  2. ‘blog posts’ is data that is created in the gulpfile.js by using node fs to loop over the jade files, and the stored in memory. From there it is passed into the Jade templates
  3. ‘blog categories’ is created in the same process as ‘blog posts’, but it is looped over to create each category


There are three ways data is used to build this project. All three methods are then passed into the Jade build using Jade locals.

  1. JSON files in /_src/markup/data => the idea here is that you can use Excel and make a datatable, export as CSV and convert it to JSON. I usually end up on this website to convert to JSON.
  2. javascript array for the websiteLinks, or sections as they are called once they enter Jade
  3. using node fs to loop over and read the files in the build to create a dataset for blog posts and blog categories


The markup is all housed in the /_src/markup directory. This is just your standard Jade build. If you don’t understand this section, learn more about Jade and come on back. The real magic is using Jade locals to pass data in, so I’ll focus more on that. A short description of each file is above in the build.


I added just enough CSS to make the page have minimal layout. This article is about the markup, so I’m not going to focus on CSS.


See the paragraph on styles above and replace ‘CSS’ with ‘javascript’.


The gulpfile.js, this is where it all goes down. You can see the whole file in the Github repo. I’ll break down each section.

The modules includes:

Some Regular Expression caching

Initializing some variables

Initializing the js objects for data storage

Storing some data

The HTML task

Use node’s fs module to read the blog directory and pass the data to the buildBlogData function

Use map to loop through the data and collect the relevant information

If the page is jade and is not the index or category page, then collect information from it

Use node’s fs.readFileSync to read the contents of each file

Add the data to the blogPostJson object

And use the pageCategories data to build out and object for the blogCategoryJson

And back the the normal gulp-jade task where we then pass all the data collected above into the jade build. The task is wrapped in a function so that it can be called once collecting the data is complete.

Build the pages with the gulp-jade task, there are three versions of the gulp-jade task. This first one collects any jade files that are direct children of the markup folder (index, about, contact, resume)

Pass the data in using `locals`, then spit the html into the root of the project.

Build the blog index and post pages, again passing the relevant data in via locals. The last line fires off the next function with data.

And build the category pages. This one loops through blogCategoryJson and builds a page for each key in the object

So now we have all the data we need available for our Jade loops. To call the data inside the jade files, you simply climb through the locals object.

You’ll notice that we call the data used on every page in the template files. (_src/markup/templates/ main.jade and post.jade)

And then we call specific data on pages where it is needed, like in the markup/index.jade file. The page loops over services and skills, so I needed to include the data there

It seems like a lot was going on, but it was really just different approaches to the same concepts.

  1. Organize data, either by creating it statically or looping though files
  2. Add data to markup, by passing the data to Jade via Jade locals
  3. Export HTML using gulp-jade

Check out the code on github

Thanks for reading my article. This is my first attempt and writing a tutorial like this, so any feedback is greatly appreciated!

If people show interest, I will write another article about decisions I made while creating all the jade files.

Web developer Daddy who is jealous of all ski bums.

Web developer Daddy who is jealous of all ski bums.