Introducing Pudl: An Easy to Use JavaScript-Based Static Site Generator
Tags: javascript, pug, sass, staticsitegenerator
Published: 2018-10-19 07:40:36

---
title: Introducing Pudl: An Easy to Use JavaScript-Based Static Site Generator
published: true
description: A JavaScript-based static site generator for quick prototyping of awesome little static demos
tags: javascript, pug, sass, static site generator
canonical_url: https://maedahbatool.com/pudl-javascript-based-static-site-generator/ 
cover_image: https://on.ahmda.ws/84543b6c78a0/c
---

Today, I am super excited to release my dev-friendly starter toolkit [`pudl`](https://github.com/MaedahBatool/pudl). In this post, I am going to share what is `pudl`, what is the motivation & philosophy behind building this dev-tooling, and the story of how I got started till its launch. Let’s start with intro first…

## 🐶 Introducing [`pudl`](https://github.com/MaedahBatool/pudl)

[](https://github.com/MaedahBatool/pudl) [![](https://maedahbatool.com/wp-content/uploads/2018/09/pudl-image.jpg)](https://github.com/MaedahBatool/pudl)  [pudl](https://github.com/MaedahBatool/pudl) is a JavaScript-based static site generator for quick prototyping of awesome little static demos while teaching/presenting. Packed inside [pudl](https://github.com/MaedahBatool/pudl) you'll find workflows for **Gulp**, **Sass**, and **Pug** to get you started. It is aimed at both beginners and professionals who are looking forward to getting a solid start for any static site. So basically, [pudl](https://github.com/MaedahBatool/pudl) is a simple implementation of Gulp which helps to perform the following tasks:

*   ⚡️ Use Pug to generate HTML files
*   🎯 Handles Sass to CSS conversion
*   🔥 Live reloads the browser with BrowserSync
*   👊 Watch files for changes

## 🎩 How It All Began?

For the past 9 years, I have been working with WordPress and during all this time I have transitioned myself through different roles like from _Content Strategist_ to _Program Manager_ and to an aspiring _Developer_. But particularly for the last 2 years since I got married to the incredible [Ahmad Awais](https://twitter.com/MrAhmadAwais) — who's a huge [open-source developer advocate](https://github.com/ahmadawais/) I have been handling the pre-development workflows for his projects. During all this time I encountered a pretty monotonous work routine which included configuring tools which rendered `pug` to `html`, `sass` to `css` and integrate live reload with BrowserSync. Moreover, I realized that at least **20% of my time** would go into this process every time I got started with any new project. So, to stop me from reinventing the wheel daily and follow the DRY (Don’t Repeat Yourself) philosophy, I decided to build a site generator with just the right features I need. When I got started, I only wanted it to cater my web-dev workflow needs. As I went ahead developing it, I realized that it could serve the purpose of several other developers as well. So, here I present [pudl](https://github.com/MaedahBatool/pudl) which is a simple implementation of Gulp for performing the following tasks:

*   ✅ Pug to HTML conversion
*   ✅ Sass to CSS conversion
*   ✅ Watch files for changes
*   ✅ Error handling and notify messages.

## 🔥 Getting Started

Getting started with [pudl](https://github.com/MaedahBatool/pudl) is way too easy. In just 4 simple steps you can §set up a basic web architecture for your development projects. And the best thing is that you don't have to repeatedly.

### → Step #0: Install Node & NPM Package Manager

In case you are an absolute beginner to the world of `Node.js`, JavaScript, and `npm` packages — all you need to do is go to the Node's site [download + install](https://nodejs.org/en/download/) Node on your system. This will install both `Node.js` and `npm`, i.e., node package manager — the command line interface of Node.js. You can verify the install by opening your terminal app and typing... 

{%gist https://gist.github.com/MaedahBatool/a90eab00aeeb9b93b12684c62b0a8898 %}

### → Step #1: Download the Required Files

Download [`gulpfile.js`](https://raw.githubusercontent.com/MaedahBatool/pudl/master/dist/gulpfile.js), [`package.json`](https://raw.githubusercontent.com/MaedahBatool/pudl/master/dist/package.json), [`.gitignore`](https://raw.githubusercontent.com/MaedahBatool/pudl/master/dist/.gitignore) and [`config.js`](https://raw.githubusercontent.com/MaedahBatool/pudl/master/dist/config.js) files inside the root folder of your project. You can also use your terminal to browse your desired folder and run the following command which will download all the required files for you via cURL. {%gist https://gist.github.com/MaedahBatool/12ddb8122bcb3a5bd7175848ad07e2d9 %}

### → Step #2: Editing the Project Variables

The next step is to change the project variables in the `config.js` file according to your folder structure. {%gist https://gist.github.com/MaedahBatool/514920a3ff5918e0919a7719d2fc74e6 %}

### → Step #3: Installing Node Dependencies

The next step is that in your root folder install the Node dependencies. In the terminal run this command and wait for it to download all the `node.js` dependencies. It's a one-time process and can take about 5 minutes depending on the speed of your internet connection. 
{%gist https://gist.github.com/MaedahBatool/b16176adfaba444bcdf9bc83df81a0ae %}

### → Step #4: Run `npm start`

Finally, run the following command to get up and running with pudl. {%gist https://gist.github.com/MaedahBatool/79aa122f77702a4fd0f6a9f723880f1b %}

Now `gulp` will start watching your `pug` and `sass` files for any changes and provides you with a link through which you can access your site locally.

## 👊 `pudl` Folder Structure

Let’s now run through the most important parts of the [`pudl`](https://gist.github.com/MaedahBatool/b16176adfaba444bcdf9bc83df81a0ae) project.

### ☑️ `dist`

Instead of several tiers, I preferred compiling all the key files into one single folder and that is the [`dist`](https://github.com/MaedahBatool/pudl/tree/master/dist) folder. The overall folder architecture is pretty much simple and easy to comprehend since the two primary files which pique your interest is the `gulpfile.js` and `config.js`. The remaining files are the `package.json` and `.gitignore`. Let's quickly study the contents of `gulpfile.js` and `config.js`.

### ☑️ [`gulpfile.js`](https://github.com/MaedahBatool/pudl/blob/master/dist/gulpfile.js) File

The `gulpfile.js` is built in such a way that it can be used with any dev project. It consists of the following portions:

1.  **Configuration & Load Plugins**: Handles project configuration for gulp tasks and load gulp plugins for it.
2.  **Task `view`**: Compiles Pug into HTML, Error Handling and Notifies for the success message.
3.  **Task `styles`**: Compiles Sass into CSS, Error Handling and Notifies for the success message.
4.  **Task `bsync`**: Injects changes and automatically open the browser with BrowserSync live server.
5.  **Watch `default` Task**: Watch for file changes and run specific tasks.

Here is the complete source code of the `gulpfile.js` file: 

{%gist https://gist.github.com/MaedahBatool/3defc7d06ff99c15f54a2d0c74aa3a79 %}

### ☑️ [`config.js`](https://github.com/MaedahBatool/pudl/blob/master/dist/config.js) File

The `config.js` has all the settings for project configuration. When you are integrating `pudl` in your development workflow editing of these project variables is a must thing to do because the folder architecture may vary from one project to another. However, I have tried to name these project variables in a way which are used quite consistently. Here is the complete source code of the `config.js` file. 

{%gist https://gist.github.com/MaedahBatool/d2e72bf05b9792d50e60006d05eb8b30 %}

## ✅ Running [`pudl`](https://github.com/MaedahBatool/pudl)

If you have been following this post thoroughly then by now I am sure you've understood the basic setup and working of [pudl](https://github.com/MaedahBatool/pudl). So, before I end this piece let me show you how it works in a real-time environment.

### → Step #1

I created a simple testing project called `demo-with-pudl` in which I directly ran the curl command which I have mentioned in the getting started steps. [![](https://maedahbatool.com/wp-content/uploads/2018/10/ezgif.com-optimize.gif)](https://github.com/MaedahBatool/pudl) [/wt_extendImage] This command will download the [`gulpfile.js`](https://raw.githubusercontent.com/MaedahBatool/pudl/master/dist/gulpfile.js), [`package.json`](https://raw.githubusercontent.com/MaedahBatool/pudl/master/dist/package.json), [`.gitignore`](https://raw.githubusercontent.com/MaedahBatool/pudl/master/dist/.gitignore) and [`config.js`](https://raw.githubusercontent.com/MaedahBatool/pudl/master/dist/config.js) files inside this root folder. Likewise, I edited my project variables in the `config.js` file and my folder architecture looks something like this: [wt_extendImage] [![](https://maedahbatool.com/wp-content/uploads/2018/10/Image-2018-10-01-at-2.15.41-PM.png)](https://github.com/MaedahBatool/pudl)

### → Step #2

Now I will install the node dependencies by running the `npm install` command in my terminal. This adds a new folder for node modules in the root folder. [![](https://maedahbatool.com/wp-content/uploads/2018/10/Image-2018-10-01-at-2.25.09-PM.png)](https://github.com/MaedahBatool/pudl) 

### → Step #3

Now it's the final part of the setup where you will run [pudl](https://github.com/MaedahBatool/pudl) to see how gulp handles all the described tasks for you. Simply type the command `npm start` and hit Enter in your terminal. [![](https://maedahbatool.com/wp-content/uploads/2018/10/ezgif.com-gif-maker.gif)](https://github.com/MaedahBatool/pudl) You are notified by a successful completion of **views** and **styles** which means both pug and sass are being rendered perfectly. Likewise, you are provided with a localhost link which live reloads for every change you make.

## And It's A Wrap!

That's about it. The idea of [pudl](https://github.com/MaedahBatool/pudl) basically originated from my personal dev-workflow needs but later it got refined and has helped me open source it to the community on an advanced level. Now I am handing it over to you and look forward to your comments. Let me know if I missed something or if you didn’t understand a step or two. [pudl](https://github.com/MaedahBatool/pudl) is now [available on GitHub](https://github.com/MaedahBatool/pudl) and is free to use. Also, it'll be great to 🌟 its repository and share it across your network. Peace! ✌️