webAppWriter
Rocket Logo Fins Blog

Friendly Customization

TL;DR:

How to stay on friendly terms with your favorite SSG when you start going deep into personalizing your theme? If you set yourself up properly, it can be easy to stay best friends.

Then you can customize and personalize your chosen theme, to your heart's content.

The tips below are less important, if you're just doing shallow theme modifications like colors.

Too Much Friendliness already?

You could say that SSGs are already too friendly for their own good. They are certainly friendlier than their UI driven predecessors

SSGs use a sequential overwrite based on inputs pattern.

There are three very serious side effects to this otherwise friendly pattern:

Since all of these are attempts to give you freedom, maybe that's why I never hear people talking about the side effects. Freedom is supposed to feel positive, not overwhelming.

But I spend unwanted minutes(?) on the side effects - sometimes on a daily basis. Maybe that's because I'm autistic so I don't shift contexts as nimbly as others? Either way, here's how I compensate for all that freedom.

The overwrite foot-gun

To illustrate, let's compare strongly typed and weakly typed languages. In strongly typed, once you establish a structure it can't be overwritten. It is simply impossible. SSGs are more analogous to the weakly typed languages - overwrites are just taken for granted, for the most part. Freedom.

Or CSS. You can set the same selector value in 10 different places in 7 different CSS files all referenced by a single HTML page. But only one has any effect, usually. Allowing that kind of freedom could be considered friendly, but it can also leave me searching dev tools for which one?

In this sense, templating systems are their own house of horrors, and they all tend to share this same foot gun. Pretty much by definition, a templating system loops over stuff and writes wherever and however it needs to, to get the job done. Overwrites aren't even discussed as an issue, they are just writes. If they also over-write, then it's just them trying to be friendly and let you write what you need to write.

What all this means is that SSGs can give you a lot of overwrite styled foot guns by trying to be super friendly. Like any foot-guns, some degree of extra care may be required if you like your feet.

Strategy 1 - It's the sequence!

How to learn what sequence the SSG overwrites?

One remedy to all that freedom is spending a few seconds really grokking the sequences that a page is written in, or CSS is applied in. If the overwrites are always in the correct sequence, it's never a problem, right? The last one was the one you wanted, anyway. Friendly!

So the first strategy is just make sure you're aware of these two specific types of sequences so you know where to apply any changes. Neither is hard to find and internalize, nor do you have to be a template coder to grasp the sequence.

Once you have these two things identified you can quickly resolve any otherwise time consuming sequenced overwrite problem. Or, as easily as possible.

Don't even get me started on the giant foot gun that CSS is.

Strategy 2 - It's the inputs!

Here's a fun twist - 11ty's best feature can break your flow - if you have what seems to be the "normal" approach to time management.

  1. 11ty is way flexible. Lots-o-different ways to do the data thing.
  2. Normal human time management means RTFM is not even the first order of the day.

#2 above works as the default, for me. Except in the presence of #1 above. That's when I wish I had forced myself to RTFM. So here's my RTFM list, in case you want travel deep into the land of customizing an 11ty site:

By this time you're beginning to maybe not wonder what "frontmatter" is, and other contextually defined words from the 11ty world.

Recapping, for emphasis: SSGs in general, and 11ty/Rocket specifically, might be easier to personalize/customize after a specific chunk of RTFM, first. Or at least that's true when it comes to taking in data structures as inputs.

Don't forget, the structured input data provided by these files is replacing an entire structured database and admin-UI for a CMS such as WordPress. There's a reason why that data is so important to the process.

Strategy 3 - It's the workflow

So I'm just going to come out and say it. SSGs are a much different workflow than other coding workflows I have used.

If you ever got coached in woodworking, someone warned you "Measure twice, cut once." A lot of coding workflows are like that. I think about the design carefully, try stuff out, then refactor after the long coding session. That's just how the process works, for a lot of us.

By comparison, I find that SSGs are more like mowing the lawn. You just, well, mow the lawn. Thinking isn't so much a part of the process, and the best part is the instant gratification.

How long does it take to run an experiment in an SSG? Sometimes it's just saving a file, you don't even have to restart localhost. Worst case is 3 seconds to tab back to the shell and control C up arrow to restart localhost, such as if you renamed a file.

So here are some guidelines that I use for SSGs, that may be different from more typical coding that you or I do as software developers.

As a result of all these high velocity trivial commits, I end up with a hyperactive git log where all the commits are labeled WIP but since most were so trivial, I never seem to care. I still do the occassional rollback, but I'll just use commit dates and fast experiments rather than try to nail the rigtht rollback on the first attempt. YMMV.

Other Rocket features you may need to RTFM

You may find these Rocket explorations handy for understanding how the various parts of every Rocket page work together.

There are, of course, other things such as the Markdown plugin that you also might want to read about, but I didn't find them very likely to get in my way during the process of customization or personalization.