Over a million developers have joined DZone.

Embracing Simplicity with Static Site Generators

DZone 's Guide to

Embracing Simplicity with Static Site Generators

Static sites can be beneficial by providing an incredibly simple output that can be deployed anywhere quickly and cheaply.

· Web Dev Zone ·
Free Resource

This article is featured in the new DZone Guide to Web Development: Applications and Frameworks, Volume I. Get your free copy for more insightful articles, industry statistics, and more!

For many years developers have made use of various application servers to create dynamic websites. From PHP to ASP to ColdFusion and more recently Node.js, app servers let you integrate databases and other dynamic features into your websites. But more recently, many developers are beginning to realize that app servers may be more power than they need. Static site generators, a relatively recent innovation, provide developers with the nimbleness of an app server while working locally and outputting simple static files for easy deployment.

Given that an app server can be so powerful, why would a developer willingly give that up?

  1. One of the biggest reasons is that an app server can go down. Every app server needs to be updated, monitored, and generally babysat to ensure it's running well and secured. On top of that, app servers are typically paired with database servers, which require the same time and care.
  2. Many times app servers provide way more power than necessary. Do you really need PHP for a site getting less than a thousand hits per month? Do you need MySQL for data that changes rarely?
  3. Another big reason to avoid app servers is that our websites are doing less and less now that so many people have moved to apps on their mobile devices. Your website may have turned into simply an announcement telling people to download your app.
  4. Finally—browsers are much more powerful now than they were years ago. Things that app servers had to do because the browsers couldn't handle it may be better handled on the client side.

For this reason and more, static site generators provide a great alternative. A typical generator will do the following for you:

  1. They will give you a template language. While not a real "programming" language per se, these template languages let you embed tokens in your code that will be replaced on the fly.
  2. To replace those tokens, they provide a way for you to store data. This is outside a database server and is generally something like a simple JSON file. 
  3. They provide a way to preview your site on your local machine, running much like a traditional app server.
  4. Then they provide a way to output to simple, static files.

Sound interesting? The good news is that you have more than a few options. The list at staticsitegenerators.net currently has nearly 450 different options. Every static site generator will have its own way of doing things while generally following the process listed above. For this article, let's take a look at a rather simple generator, Harp (harpjs.com).

Working With Harp

Harp isn't the best generator out there, and it isn't even my personal favorite, but it was the first one I encountered and was responsible for starting my love for generators in general. It's also one of the simplest ones to get started with, and that makes it a good option to discuss. Keep in mind, though, that if you don't like the particulars of how it works, you still have over four hundred other ones to try. (I'll discuss some other options at the end of this article as well.) To begin, simply npm install -g harp. This will add the Harp command line to your system. To confirm, just run harp at the command line.

Image title

Harp's command line mainly revolves around three options— making a new site, running the server, and outputting static at files. Let's begin by creating a new site: harp init demo1.

Image title

This will create a simple site with four files:

  • _layout.jade handles creating the layout for the site.
  • 404.jade is a 404 handler for the site.
  • Index.jade is the home page.
  • main.less is a style sheet written using Less

For rendering HTML, Harp supports Markdown, EJS, and Jade. For rendering CSS, Harp supports Less, Stylus, and Sass. You can even use CoffeeScript as well. Harp automatically converts the particular language into the right output. Let's see this in action. At the command line again, run harp server.

Image title

If you open this up in your browser, you'll see the following:

Image title

So how did this work? By default, Harp's initial files are all using the Jade template language. Jade was recently renamed to Pug, and you can nd documentation about all it supports at its website: pugjs.org. But for now, open up index.jade:

Image title

Even if you've never seen Jade before, you can probably guess as to how it is working. The first line is creating an h1 block with text inside it, and the second line is creating an h3 block. Modify the template like so:

Image title

All we've done is added a new paragraph with a bit of styled text. Reload the page in your browser and you'll see the new output:

Image title

If you view the source, you'll see HTML, not Jade. This is—pretty much— like every other old app server out there. PHP acts the same way.

Now let's create another file, about.md:

Image title

In order to use global data, you must use the file named _harp.json (there’s an exception to this, but don’t worry about that for now) and an object defined with the name globals. Outside of that, you can then use whatever variables you want. In the example above, two variables, email and name, are defined, but that’s completely arbitrary. You can include any valid JSON you want here.

Once defined, these variables will be available in all your files.Here’s an updated _layout.jade file that includes the name value as the title:

Image title

And here’s a modified home page using the email:

Image title

While not as powerful as a proper database, we now have one place where we can define dynamic values and have them automatically updated throughout the site.

For the coup de grace, let’s now kill off this server and output in static files. That takes all of one command: harp compile -o ../ demo1_output.

This tells Harp to compile the current directory and output it one level higher in a folder called demo1_output. This will create four files: 404. html, about.html, index.html, and main.css. If you open index.html you’ll notice the layout and variables have all been rendered. You can now take these files and deploy them as a simple static site.

Harp has more features than we’ve covered here so be sure to check the harpjs.com/docs for more information!

Adding Dynamic Back

So obviously once you’ve gone static you end up losing a few simple things you may miss. One example of that is form processing. How do you add, for example, a basic contact form to your site so visitors can contact you? Luckily there’s a few options for this. One of the best, and easiest, to use is Formspree (formspree.io). With Formspree, you can simply point your form to their server, include your email address, and they will forward along the results to you. Consider the following example:

Image title

In this rather simple (and kinda ugly) form, the action points to Formspree and includes my email address. Now when the form is submitted, Formspree will take the contents and email them
to me. The very first time this happens Formspree will require you to confirm that you want the form to work, but after that it’s automatic. You can even tell Formspree where to send the user next by including a hidden form field: <input type="hidden" name="_next" value="some url on your site telling the userthank you">.

Formspree is a great service with a very generous free tier. Check the site for current costs and what’s supported at that level.

On top of forms, you can also nd services for calendars, comments, and other dynamic aspects.

Wrap Up

While obviously static site generators aren’t going to be a good option for every site, it’s amazing how many places they can be used. As much as I consider myself a decent developer, I absolutely love the idea of my production websites being as simple, and stupid, as possible. The fewer things I have to worry about breaking down is always a good thing!

More Web Dev Goodness

For more insights on working with the latest frameworks using third-party APIs, implementing module JavaScript for clean and reusable code, and more, get your free copy of the new DZone Guide to Web Development!

If you'd like to see other articles in this guide, be sure to check out:

web dev ,static sites ,harpjs ,app server

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}