I'm making a new website.

Background

A couple months ago I wrote about why I liked Markdown so much. Even though I have been using static site generators for over 10 years, and even though they do great, they haven't always satisfied every need that I have. They still produce a static site, and they haven't always delivered the stability that I need with some of the features you'd think they'd promise.

Static Site Generators

The whole idea of a static site generator is that you focus on the content rather than the formatting. Static site generators take in text files -- usually markdown -- which is little more than a text file with very light formatting guidelines baked in, and merge it with a template and theme of your choosing to produce a pretty, content-focused website. For me this was a game changer because it meant that I could twiddle with the details for a finite amount of time and then get down to writing. For me, fiddling with formatting always was a useful procrastination tool, and eliminating it from the writing process was key to keeping me focused longer.

Because static site generators depend mostly on markdown as the user-generated input for a new page, they have traditionally been oriented towards blogs and personal websites... anywhere where you can apply a consistent theme to every page and any customization can be provided by relatively straightforward tags, variables, or by organizing your content into themed directory structures where each directory might have a slightly different theme applied to it. If you want custom pages you need to fall back on HTML, and the theme and template of your choosing to produce anything that falls out of that norm. Therefore, one of the challenges in creating a static site is selecting a theme that matches your needs. Often you have to start with someone else's theme and then heavily modify it once you realize it's missing a key functionality.

Jekyll: The OG SSG

Over the years I have tried several different static site generators. First Jekyll, and then Hugo, and more recently MKDocs. Jekyll was a great entry-level static site generator written in Ruby that allowed me to apply what little I knew about web development to quickly get a small site up and running. Because I was using GitHub to host my site, I could start with a relatively simple project, and not worry about the build environment because it was included within GitHub. If you wanted to embed some customization into the page, you could embed it using templating logic that you could directly include into the HTML theme. The site would then use those tags to generate custom content on your page based on input data that either came from the markdown header or other external files. I was using Hugo before much of the templating could be subdivided and obfuscated away so I was quite used to a monolithic project that mixed both my content and my format.

Over the years, as my site grew, however, Jekyll started to struggle to process the hundreds of pages, many of which included nested for loops and other complex templating logic that had started to outgrow its build tool. It would take five to ten minutes to generate the site after a small change, and if I happened to make a mistake, it would be quite a long time before I could iteratively guess and check my way through a fix. I'm sure this is because my use of the templating engine grew and the complexity of the different kinds of pages I was generating grew with it. Something that I had liked at the beginning, which was the inclusion of templating engine tags directly in the HTML and the project I was working on, slowly became a chain around my neck that was dragging me down, making my project more cumbersome and breakable.

Another issue that began to crop up was as I became more and more dependent on plugins and options that were custom to specific package versions, I had to create and maintain my own specific Jekyll build environment. Installing Ruby on Rails and all of the packages that I needed started to become more arduous as versions began conflicting with each other, died, or upgraded. My knowledge of Ruby and package management within the Ruby ecosystem had always been quite limited, and I never invested enough time to become an expert in it. But I also suspect that it also became more complicated as the years went by. By the end of my time using Jekyll, I had needed to create and maintain a custom Docker environment for each site, just to be able to build each website. This was a big deal at the time because I didn't really know Docker either.

Hugo: The promise of speed

So I switched over to Hugo because I had heard so many good things about compile speed. Indeed, it was fast. Hugo also advocated the division between content and theme, which I really appreciated as I had come to fear the complexity of my own project. I jumped in headfirst and converted many of my old Jekyll websites into Hugo websites.

And yet, some small niggling issues kept me from loving it. Hugo's documentation is vague at best. Even though they may have quite complete documentation covering every function and variable, it's more of a list of functions rather than an exhaustive set of examples, and unless you are already an expert at it, some of their explanations for how to use specific templating functions could be interpreted a number of ways. Understanding Hugo's limits became an iterative testing and checking process, and one that was not fixed by a standard, but constantly evolving with each version.

With documentation not so helpful, I struggled to find solutions to the kinds of problems I was looking for. A lot of solutions in their forum were from versions long ago that no longer applied, and no one seemed to be asking the questions that I was. Whether it was or wasn't, it felt like a small community. And very much like Jekyll, the time I spent developing the website had been at a very specific point in time. Yet, later, as I maintained it, and as the slow march of versions went up and up, my sites would suddenly stop building on the latest version of Hugo.

So here I am chaining myself to specific tool sets that are highly dependent on the combination of versions that I happened to use at the time. They are complex to learn, and yet still complex to maintain. Yes, I could make daily changes for a year or two without event, but sooner or later the system would break down, and I would have to go digging into the guts of my theme, my HTML or cycle through versions of the static site generator itself itself to understand what had changed and what I had to update to make my site build again. A lot of that long-term payoff promised by the idea of static site generation was left unrealized.

Aside: MKDocs is great

I do want to give credit to MKDocs, however. This handy tool has been the answer to many of my needs coming from the other two tools, and it solved it in a way that I didn't expect. No, it is not as customizable at first glance. But it is a batteries-included experience, especially if you use the material theme. The installation process is a lot simpler, especially since I am a python nerd and know how to work with Python environments. But more importantly, even though I've been using it for about five years, it seems to have remained much more consistent in producing buildable sites that don't need my intervention to continue working. This is because I rely less on a complex web of external plugins. The core functionality of MKDocs produces very usable sites with many different built-in plugins that are maintained by the MKDocs team. The one exception is the material theme. With this one theme, all of my other needs are generally supplied.

Realizing some gains

There had been another payoff. I had switched my life over to Markdown and it was now my medium of exchange. I have now used markdown for over 10 years now in all sorts of situations: for documentation, course material generation, and websites. I have also used it to generate my textbooks to generate slideshows. And the coolest part is that I can use the same material with minimal changes across vastly different formats and maintain a source code repository that has to change very little to be used in those different contexts. In conjunction with pandoc, hugo, latex, MKdocs, and other similar tools, markdown is now the way I compose and store the things that I write... And I am not about to change that.

Looking forward

So now what do I do? Looking forward, I am hoping to need more functionality then a static site generator . I want my new website to look unique as well. This leads me away from static site generation and MKdocs, even though it is great for what it does. But I wouldn't like to abandon the mental approach of writing in Markdown.

Now that I've set up the problem, follow my next post to find out where I am headed, what tools I've chosen so far, and some of my rationale. This is available in next week's post.