Two Features Of Site Generators I Cannot Go Without

20 December 2019

After realizing that React, Vue.js, EmberJS and other JavaScript frameworks are tools mostly for creating Single Page Applications, now I concede that inventing such an application is not necessarily the most effective way to launch a blog. What confused me is the phenomenon that these frameworks - along with everything related to web development in general - got so much attention and popularity, that I wanted to believe that they are the new basic building bricks for anything related to modern web development and therefore somehow will solve all my problems.

Tools

Now I realize that these are great tools, nonetheless only tools. A tool usually provides great help for some tasks, but not for everything. One gains the most if the right tool gets used for the right job. My last question was for myself - what is that particular task exactly?

Redefining the goal

Web development is a huge topic - it must be, considering the web being only a medium. I think, that at its foundations, web is only a document formatted in a way that it looks great in common renderer programs called browsers, maybe with some rudimentary support for interactions here and there. That’s it. Therefore, when I say I would like to create something, I have to be somewhat more specific.

If I was about to create a software for book keeping, googling “making a C++ program” won’t help me, neither would “making a book keeping program”. I must know exactly what are the minimal features that I would like to see in that program and then it is my job to scaffold it.

Let’s dream a little

Okay, let me draw my first ideas and see what is feasible and what is not.

drawing

Not really artistic but it does the job for a starting point.

Implementation

If I wanted to create a site like the one above, I could probably just tailor and edit together some html & css, maybe in a single file and release it.

The problem comes when I want to reuse the base layout.

layouts drawing

On this drawing I tried to separate the “look and feel” of the site to be created highlighted with blue, and a place for the content.

Given that I have a single html file bundled with all the resources, I could just copy and paste this page whenever I create a new post.

However, at this point my layout is hard-coded and burned into my site. At the time I will be about to write, say, the 7th post, it will be almost impossible to change anything marked with blue. These are copied over and over again and now I have to edit all the instances one by one.

Should we use templates, then?

Let us think about WordPress again, particularly what it gave us. We could just write the content of the post - none of the design:

WordPress post writing

…and then it would substitute the content to our site to the part marked with white on my previous drawing.

If I wanted to change anything on the blue part, I could do it one place!

That is the main advantage we get when we separate our concerns. The design and the content are two separate problems and therefore shall not be lumped together, only at rendering. A generator is a tool that “bakes” our site based on the recipe we gave, resulting in the html files we would have hand-crafted if we would have followed our first approach. However, we will have the original sources after rendering, ready to be modified and rendered again. Therefore, we won’t manipulate the html files one by one. We will generate them.

So all we need are layouts?

Well, I think, there is one more design approach that is also useful in templating. Looking at this picture:

components drawing

What if I would like to have special pages, where only the content is visible and there is no “sidebar”? Or what if I wanted to place the highlighted elements sometimes below the contents, for example, while creating a responsive view - given that I can not practically solve it with pure CSS?

Of course, I could create a new layout - and that is exactly what I would do in that situation - but I may have to copy those blocks of elements. If I copy the social media icons and later change them, I have to do it in every layout where it got used. Again, we are copying code.

Widgets (or modules, or includes, etc.)

I think it would be a good idea encapsulate these elements and reuse it across layouts. We have separated the concern of laying out our site and designing widgets.

When I change the layout I won’t have to bother these widgets, and when I want to change one of these widgets, I only have to change them at one place.

The two most important features

At staticgen.com we are to find an intimidating amount of static site generators.

staticgen.com digest

My experience tells me that choosing one of these tools judging by only the number of stars on GitHub is a really poor practice and may cause huge time costs failing to use one or the other, especially when one does not know what to do - like me the first (and the second and the third…) time.

Therefore, before choosing we need to identify what we want from these frameworks. In this “episode” I have identified that I need at least

  • Reusable layouts
  • Reusable widgets

To be continued

Next time I am going to enumerate the remaining features I need by all means, compare some of the options I have encountered and justify how I made my choice.

Thanks for reading!