Getting Started with Wintersmith: A Node.js-based Static Site Generator

Originally published at: http://www.sitepoint.com/getting-started-wintersmith-nodejs-static-site-generator/

I’ve spoken and written on the topic of static site generators a lot lately. Generally speaking, I tend to recommend going with Jekyll as the most stable and feature-rich option for building static sites available today. However, the fact that Jekyll is Ruby-based can be a deal-breaker for some developers, especially those not familiar with Ruby. The single most frequent question I get is: “Is there a good option based upon JavaScript and available via npm?”

In this article, we’ll cover one such option, Wintersmith. Wintersmith is a robust static site generator with one biggest impediment being (in my opinion): a lack of detailed documentation. Hopefully this article will help anyone interested in a JavaScript-based option available via npm to get started building static sites with Wintersmith.

The Sample Site

For this article, we’ll use the sample site I built and that you can find at my Static Site Samples repository. The sample is an Adventure Time! fan site that looks like the image below.

The goal of the project was to rebuild this site using a number of static site generators to compare them. While the site is intentionally simple, it contains a number of key features that we’ll look at in Wintersmith:

  • Custom global metadata – the ability to set custom metadata global to the site that can be accessed and used in templates;
  • Custom post metadata – the ability to set custom metadata on a per post basis that can be accessed when listing the post or in the display of the post itself;
  • Data sets – the ability to add content that is not a post or page, but rather a custom data type (in the case of this sample that is the character data).

All of the character data, content and images used in the sample are from the Adventure Time! wiki. The design was based upon a free template from HTML5UP.

How to Set up Wintersmith

One of the benefits of Wintersmith being based on Node.js and npm is that the installation process is super simple. You have to execute the command below to install it (note: the sudo isn’t necessary on Windows):

Continue reading this article on SitePoint

Hey Brian. I was wondering how many other Node/JavaScript based static site generators you’ve tried. I know I saw a presentation you did on a few different SSG’s not too long ago and the one JS one you presented was something you hated (because you hate Jade… which makes this article a bit ironic). Anyway since then, I found https://www.staticgen.com/ which lists tons of these SSG’s and I grabbed the JS one with the most stars (Hexo) and so far I like it. I want to make sure I get the real deal, though, so if you’ve tried Hexo, it’d be cool if you could give a comparison. Otherwise I could be like you and try way too many of these things myself. :slight_smile:

There are TONS of these - https://staticsitegenerators.net/ says there are almost 400. It’s nuts. Anyway, I have not messed with that many of the npm options. Spent a lot of time with Harp as well and worked a bit with Metalsmith. I have not tried Hexo but it looks like it has potential. At least it is documented (a total copy of Jekyll docs but that’s ok, as the Jekyll docs aren’t bad). I like the command for new posts and the assets folder - Jekyll doesn’t even have these. I’ve never used Swig (jeez, another template language!) but it looks similar to Liquid. I actually have a presentation coming at JekyllConf (online event) comparing Jekyll to the competition and will have to add this to the list.

Fwiw, I still hate Jade. I tried not to harp on this topic in the article - didn’t want to be too negative.

Yea, for the most part, I like Hexo’s documentation, but it is sometimes lacking some information or uses a pretty terse answer that doesn’t really help much, especially for configuration. It also seems pretty flexible regarding the templating languages you use, which can actually be annoying since none of the themes I downloaded to look at used the recommended Swig, though that may have something to do with the fact that they recently switched to it in version 3.

I’m not really sure of the point of Swig… it’s so similar to so many other templating languages, but at least it isn’t Jade :stuck_out_tongue:. I wish people would stop making alternatives and just help out on projects that already exist unless you’re actually working to create something completely different. Same goes for sooo many open source projects.

I personally like the idea of Jade’s syntax, but I can’t bring myself to learning a completely different HTML syntax. Most templating languages allows you to only need to learn new code for the dynamic markup, but let you use plain HTML everywhere else, which is a huge plus. Once you get used to Jade, it can help speed up development, but it’s just another language you need to learn because you still need to know HTML.

Btw, you spurred me to write a version of that demo using Hexo. About to post it to my GitHub repo. The documentation wasn’t as great as it looked. It lacked so many important details that cost me hours of effort and a lot of frustration. In the end, for instance, one thing I just lived with the workaround because I couldn’t get it to work the way I’d expected.

Net result, I still like Jekyll best. If you must use Node/npm, then Wintersmith still wins.

This topic was automatically closed 91 days after the last reply. New replies are no longer allowed.