DEV Community

Cover image for Introducing Pudl: An Easy to Use JavaScript-Based Static Site Generator
Maedah Batool šŸ‘©ā€šŸ’»
Maedah Batool šŸ‘©ā€šŸ’»

Posted on • Originally published at maedahbatool.com

Introducing Pudl: An Easy to Use JavaScript-Based Static Site Generator

Today, I am super excited to release my dev-friendlyĀ starter toolkitĀ 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

pudl is a JavaScript-based static site generator for quick prototypingĀ of awesome little static demos while teaching/presenting.Ā Packed inside 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Ā 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 ā€” who's a huge open-source developer advocateĀ 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 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 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Ā 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...

ā†’ Step #1:Ā Download the Required Files

DownloadĀ gulpfile.js,Ā package.json,Ā .gitignoreĀ andĀ 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.

ā†’ 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.

ā†’ 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.

ā†’ Step #4: RunĀ npm start

Finally, run the following command to get up and running with pudl.

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 project.

ā˜‘ļøĀ dist

Instead of several tiers, I preferred compiling all the key files into one single folder and that is the 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Ā 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:

ā˜‘ļøĀ 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.

āœ… Running 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. 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. [/wt_extendImage] This command will download theĀ gulpfile.js,Ā package.json,Ā .gitignoreĀ andĀ 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]

ā†’ 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.

ā†’ Step #3

Now it's the final part of the setup where you will run pudl to see how gulp handles all the described tasks for you. Simply type the command npm start and hit Enter in your terminal. 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 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 is now available on GitHub and is free to use. Also, it'll be great to šŸŒŸ its repository and share it across your network. Peace! āœŒļø

Top comments (15)

Collapse
 
lysofdev profile image
Esteban HernƔndez

You could distribute this as an NPM package with an executable pudl

Collapse
 
geoff profile image
Geoff Davis

This. There are many if not most devs that know how to use curl/git to setup a project, but it seems unnecessary considering we already have tools to distribute and properly manage versions of projects like this.

Anyways, looks cool! Always enjoy seeing Pug around

Collapse
 
lysofdev profile image
Esteban HernƔndez

Considering the limited amount of source files, this could all be packaged as templates then a CLI interface would gather the values necessary to render the templates customized for a new project (project name, authors, description, license, etc.). Using templates removes the dependency on Git even though I believe Git is a dependency of Node so should always be available.

Thread Thread
 
ahmadawais profile image
Ahmad Awais āš”ļø

Wonderful idea, how about you reach out and contribute. It's all open source and it's #Hacktoberfest as well. I think she wanted to do just that.

Thread Thread
 
lysofdev profile image
Esteban HernƔndez

Would love to contribute. Didn't see a project site tho.

Thread Thread
 
ahmadawais profile image
Ahmad Awais āš”ļø

Oh sure, here's the GitHub link github.com/maedahbatool/pudl let's do it :)
Peace! āœŒļø

Collapse
 
ahmadawais profile image
Ahmad Awais āš”ļø

As far as I know, she's already working on it for the next release. šŸ˜‡

Collapse
 
maedahbatool profile image
Maedah Batool šŸ‘©ā€šŸ’»

Hey, Esteban!

That's the plan. I am working on the next release and that is going to be in it.

Peace! āœŒļø

Collapse
 
bartosz_io profile image
Bartosz Pietrucha • Edited

Nice! But what are the benefits over for example MetalSmith?

Collapse
 
kayis profile image
K

Haha, yes.

I think this is an excellent project and the fact that a "WordPress Core Contributor" built it seems intriguing, but the first thing I wanna read in such posts are comparisons to other tools like this. I mean "my personal dev-workflow needs" implies that something wasn't quite right with Gatsby, MetalSmith, OctoPress, etc.

Collapse
 
ahmadawais profile image
Ahmad Awais āš”ļø

This is wonderful, Maedah! It has already helped in my workshop yesterday ā€” waiting for the v2 release with an npm package.

Collapse
 
maedahbatool profile image
Maedah Batool šŸ‘©ā€šŸ’»

Sure thing! Working on it.

Collapse
 
revskill10 profile image
Truong Hoang Dung

Why do people keep reinvent the (old) wheels when we have better things to offer ?

Collapse
 
maedahbatool profile image
Maedah Batool šŸ‘©ā€šŸ’»

When I looked at my work routine, then the setup of basic web architecture for a new project was something which took more than 20% of my time. And reinventing the wheel daily was something which was bothering me a lot.

I figured out the basic needs of my web-dev workflow and realized that it shouldnā€™t be that hard to build something small, with just the right features I need. pudl actually helps me not to reinvent the wheel daily.

I just open-sourced it so that others can take the benefit of it. :)

Collapse
 
shoptechmedia profile image
shoptechmedia

nice one..