Blitz: Yet Another Static Site Generator

Abstract

A small disclaimer: I was planning to write this article for a long time now, and somewhere between now and the time I released Blitz I've realised that this project was doomed from the start. Initially, this post was going to be about me telling you how cool Blitz is, but that didn't work. So now I'm just gonna tell you that Blitz happened, and it was great while it lasted.

There are times when I suffer from the NIH syndrome. Back in my high school days I used to write everything from scratch - I once even attempted to reinvent Photoshop using PHP (don't ask me how that went).

Throughout the years, my programming experience was growing and the amount of free time I had was shrinking, so I had to (forcefully) contain any NIH tendencies that I had. Luckily, that didn't always work! When I was working on the PEACH Reality project one of the requirements was to make a simple static website. That website would contain an overview of what we've done, user manual, and some other things, practically a bunch simple HTML pages with basic styling.

If you know me personally, you'd know that I'd never be satisfied with completing such a simple task without adding a bunch of all-nighter-worthy extra features. After trying a bunch of existing static site generators, I decided that none of them were worthy of being used by me. And this, ladies and gentlemen, is precisely how Blitz was born.

Blitz

Blitz Static Site Generator

The first version of Blitz was published on its GitHub on November 12, 2016. Since then Blitz got its own website - https://getblitz.io/ (which is now dead, obviously) and a bunch of updates. All 0.1.* releases had some nice basic functionality to them, but I never got to publishing 0.1.6+ which had all the cool features like advanced menus, IDs and so on. Instead, I was just keeping 0.1.6+ to myself and reaping all of its perks, har har har. You might also enjoy some trivia:

  • Blitz was my first published NPM package (I now have 3, wooo).
  • Blitz was developed in a series of all-nighters amidst university deadlines and upcoming presentation to corporate VP of Microsoft.
  • A bit of background on how Blitz generated pages:
    • You create some .pug files to define the "skeleton" of your website. Pug is just a very nice HTML templating engine which makes your HTML pages smart.
    • You write up some content in .md files because Markdown is awesome. You can also augment your .md files with front matter (concept shamelessly stolen from Jekyll). Front matter can define all sorts of useful things for your templates, like page ID, page title, menu title, etc.
    • You create blitz.yml that tells Blitz how to map your content to your Pug templates. Here you would specify menus, page URLs, etc. What I personally find cool is that you could choose a single template, and then pipe all .md files from some folder into it, without having to create a setting for each page separately. For example, you could create a blog-post.pug, then make it use all .md files from posts/ effectively generating a page for every blog post you had.
  • Blitz had an amazing feature of generating "offline" websites. As you might know, if you open a website locally (i.e. by simply clicking on .html files, without a server) most of the links tend to break because they rely on absolute URLs with respect to the website (e.g. https://foxypanda.me/some/path/). Blitz could generate websites where all images, stylesheets, JavaScript files and (!!!) menus would use relative paths (e.g. ../../image.png) so your website would work anywhere. "Menus" is emphasized because damn is it hard to work with multiple menus while generating HTML files in different folders.
  • ...because Blitz is absolutely awesome, it didn't stop on offline websites. As you might also know, server software (like Apache) usually serve the path/index.html file automatically if you make a request to path/. Blitz made use of that (and generated tons of directories) so you could get pretty, user-friendly URLs even if your website is static: http://<name>/about/, http://<name>/blog/post-1/, http://<name>/blog/post-2/, etc.
  • A small but nice feature - Blitz actually told you what element in the menu was the "active" element, so you could add some nice styling to it.
  • Now a killer feature: "Killer" not necessarily because it's cool, but because it was damn near impossible to implement. In fact, one of the main reasons v2.0 came to be was to solve this issue. Anyway - Blitz allows you to reference pages by IDs on any other page. This means if on your /blog/category-1/post-3/sidenote-1/comments page you'd want to have a link to the "About" page, you could simple use one of the Handlebars helpers Blitz provides. Now remember, as a developer, I had to deal with the case of you using relative URLs.
  • Blitz strived to differ from other static site generators, but for some reason it chose to use YAML for its config although there was really no reason to use it, Tim. Because YAML isn't very smart (unless you mod it) configs got very repetitive for big websites:
# Snippet from `blitz.yml` of a big website
pages:  
  - uri: '/'
    content: 'overview.md'
    template: 'overview.pug'
    menus:
      - name: 'main'
        title: 'Overview'
      - name: 'overview'
        title: 'Overview'
    child_directories:
      - uri: '/'
        name: 'overview_pages'
        template: 'overview.pug'
        directory: 'overview'
        menus:
          - name: 'overview'
  - content: 'research.md'
    template: 'research.pug'
    menus:
      - name: 'main'
        title: 'Research'
      - name: 'research'
        title: 'Research Overview'
    child_directories:
      - uri: '/'
        name: 'research_topics'
        template: 'research.pug'
        directory: 'research'
        menus:
          - name: 'research'
# ... and it kept going for 100 more lines.
  • Blitz had a super cool 2.0 version in the works, development of which begun in December of 2016. It had tons of bug fixes and tons of improvements, including real-time updates, preview server, config validation...

Conclusion

I absolutely loved writing Blitz. BUT I really, really, really had to limit the scope. My software engineering lecturer, Graham Roberts, would be disappointed by the amount of scope creep I have allowed. I would also definitely not use YAML again - if anything, I'd stick to JS-based config files so my users would get all of the perks of an actual programming language.

These 2 things aside, my main mistake was to allow the architecture to get super complex. I should've developed a nice, simple abstraction first and then develop the project around it, instead of doing it the other way around. All in all, Blitz was a great programming exercise.

Lesson learned, project abandoned.

If you found this post useful, feel free to like and share:

Comments