So I started out with the idea I was going to write a blog. This would be my first hands-in-the-dirt website creation activity for several years. I was prepared to discover that the world had moved on, and that there would be new tools and new ideas to digest.
Of course, I was right 🙂. On the one hand, I like being right. On the other hand, I hate wasting time. So what was the simplest approach I could take to putting some content on line ?
It's been impossible to avoid Markdown for several years now. It's used for document creation in a wide variety of domains where simple but portable formatting of basic, fundamentally textual, documents is useful. I'd come across it at work, and figured it should be my starting point.
Which is not to say that I didn't consider other things. What I understood was that there were two basic, high level approaches.
The 'modern' approach involves use of a Content Management System to generate the actual content of your web pages from an array of different types of asset. Of course, you need to tell the CMS how to build your site, and so CMS's come with scripting capabilities in a huge range of different languages. And then there are libraries of themes, plugins, and other sorts of asset that you are expected to choose or create, and then integrate and configure. And finally, there are the words and pictures you actually want the world to see.
Some CMS's are geared towards Blogging, some towards commerce sites, and some are very general. But the more I dug into the likes of Wordpress, Joomla, Drupal etc, the more it seemed to me that I would end up spending more time making design decisions, tuning things, and building workarounds than I would actually spend creating content.
The simplicity that these things trade on is relative - they are a relatively simple way of doing sophisticated things, if you want or need to do those particular sophisticated things. That doesn't, in my terms, mean that they are simple. There are still many balls in the air.
Also, although the main tools in this domain advertise tens of thousands of themes and plugins, what if you want to do something slightly different ? What's the incremental cost of a small deviation from the norm, if that is even possible ?
I've not made any remarkable discovery here. It would seem that others have, many times over and from numerous different perspectives, reached a similar conclusion. For some purposes, CMS's are essential, but CMS's are Not Always The Answer. One point that doesn't immediately leap out from my comments above is that CMS's are regenerating your website whenever content is requested. This is often hidden from you, as a service user, but it's not hidden from the folk running the infrastructure - processing costs money, and takes time. Even caching, to avoid the processing, costs money.
The result is what I call the 'old new modern' approach, otherwise known as a Static Site Generator. I'm not certain that it's current popularity is really driven by end users - or at least, not by bloggers. Most bloggers aren't asking hard questions about the underlying technologies if they can get a sexy looking thing going for a few $$$ ( or no $$$ ).
Where a CMS will sit in the background on your server, constantly building assets and web pages as they are demanded according to need, throwing in whatever scripts and assets happen to be current, according to whatever rules you have specified, an SSG will let you just build a bunch of files once on your local machine. Building stuff again is up to you - it's not part of an SSG's purpose in life to constantly regenerate your website. If you want to do that, it's up to you to make it happen. Publication of your new site is also not automatic ( although can usually be automated ).
Superficially, this sounds simpler than using a CMS. It harks back to the early days when website building tools like Dreamweaver were state of the art, and dynamic content was rare. I was attracted to the idea of using an SSG, very largely because I wanted to focus on the content I would be generating, and not on the mechanism I would need to use to turn it into a website - SSG's seemed to promise a 'simpler' route than CMS's.
In fact, this turns out to be only nearly true. This may count as false, depending on the way you take your logic 🙂. There exist literally hundreds of SSG's. This in itself is revealing. It tends to suggest that not only is there no well accepted definition of what an SSG must do or be, because so many variations adorn themselves with the label, but that it is relatively easy to create something that qualifies. There are, however, a few tens of major players, of which I've looked at about three. So statistically, I'm doomed 🙂.
< TBD >
Initially Jekyll looking promising. But I soon encountered some problems. Using Jekyll revolves around the use of Ruby, which happens to be one of the several hundred ( maybe thousands ) of languages that I don't know. Do I want to learn Yet Another Language just to put up some simple markdown ? Probably not. Do I want to use Jekyll's site structure ? No, I already have my own. Do I want to use Jekyll's templating tools ? No, there's not going to be any templating. Am I interested in Jekyll's gem ( i.e. Ruby ) based theming ? Nope.
So that was that for Jekyll. A working environment ( Ruby ) I wasn't familiar with, too many assumptions, much too much stuff I just didn't need.
Pandoc converts marked up document formats. So it converts markdown into html. It describes itself as a Swiss Army knife, which is a warning sign before you start. But it's a ten - tonne Swiss Army knife. Very big, laden with feature after feature, a man page longer than War and Peace, with some key assumptions thrown in. One of the latter is a requirement that you provide metadata about your documents.
If you really are in an environment where you have a multiplicity of document formats to manage and convert in a structured manner, Pandoc is for you. However, after spending an hour reading part of the man page trying to work out how to just feed in one of my raw markdown docs and get a simple html file out, I decided it wasn't the solution I was looking for.
Eventually, after contemplating all of the above, what I ended up with was a feeling. I felt that I might easily spend just as long learning how to beat a complex tool into doing something that approximated to what I wanted as I would writing the tool that would do just what I wanted.
Of course, this isn't an option open to everyone. Not everyone codes, even if politicians are happy to hypocritically opine that dammit everyone should because that will mean more people with high paying jobs ( paying more tax, and helping to stuff money into the pockets of Megacorp shareholders - a very fine rabbit indeed, if you are a politician ). And writing even simple programs can pose problems, some of them interesting, most of them just annoying.
If you are one of these people, that's cool. You will need to rely on Someone Else's Code ( as everyone does, even coders ), but as noted above you are not short of options. I wish you the best of luck, and even some sympathy.
However, I do code, and so a star, aka my latest little code doodle, was born. It's a doodle, because it fits in one bash script, one C file, has one dependency, has a one line makesystem, and was designed for me, not you. You can, of course, hack it yourself - it's on my gitHub here . I'll describe it ( or more importantly, it's assumptions ) below.
I don't consider it a Static Site Generator, although the site it generates is certainly static. As noted below, it lacks two key things - explicit support for templating or any sort of formatting beyond what you can do in Markdown, and any connection at all to any sort of Document management or version control system. The former is distinctly deliberate, the latter is really something I consider incidental - you can certainly put your markdown content in Git or any other VCS and manage it there, that's your call. What you're reading here is the proof of the pudding.
The project is called 'webpages', because that's what the output is.
Where I started was the question of how I wanted to prepare my blog material. I decided to use markdown, and I also decided that I'd structure the blog as a hierarchy of folders, each of which would contain one markdown file ( plus any other assets unique to that file ) with the same name as the directory containing it. Therefore there would be a 'root' folder under which all content and assets would live.
There's a question about 'which markdown' to use, because there are a zillion different flavours of markdown, and whichever I picked I would need to convert to html. Fortunately, there is something called 'Commonmark', which is an attempt to standardize ( or at least, to fully document ) a version of markdown.
The Commonmark people have ( with one annoying exception ) done a pretty good job, and there's an OSS Commonmark library that will parse ( i.e. generate an abstract syntax representation for ) the markdown and render ( i.e. translate the ASR ) into HTML. You will not fail to note the exception if you examine the source code comments in my C file.
Then there was the question about how to style the blog. This is one area where a lot of complication tends to creep in, so I really wanted to keep things simple here. I was not going to create a monstrous carbuncle of templating mechanisms. Or even a beautiful carbuncle. I can do without panels for this, sidebars for that, divs for everything, rewriting scripts etc etc. Been there, done that, and a desire to avoid all the work that entails was a consideration when starting this project. Content is king. If I ever want that sort of thing, well, I know what I'm letting myself in for.
I decided to allow myself the luxury of CSS, to provide some basic typographic features. Therefore my task was limited to providing a way to pull CSS into my HTML. You can make the CSS any way you like - that isn't a problem I'm concerned with here.
But I also did not want to assume too much. This is a key overarching theme of the whole effort - don't assume that you know what the user wants in their HTML, even if you believe they need it. So including any CSS is optional, along with several other basic things, and the CSS to be included can be made specific to a particular markdown file, or all the markdown files beneath a directory in the hierarchy. The mechanism is simple - from the directory containing the markdown file, I search that directory and successive parent directories for a CSS file, and link to the first one I find.
This 'lack of assumptions' approach extends to allowing the user to inject 'stuff' ( which I assume would be raw html, but mine not to reason why... ) into the head of the page.
Finally, because this is my tool for my purposes, I provide the ability to include what I call an 'embedded navigation link', which may one day be relevant. If you want to know what this is about, read my Navigation Model blog post.
My view on this is that yeah, sometimes you want to version control a website. But my blog is not such a critter. Note that I'm not talking about version control for the webpages tool itself here - this is about control of the website that the tool generates.
The point of using a vcs like Git or SVN is two fold. Firstly, you may need to develop and merge contributions from multiple sources, and secondly having a record of how things got to be the way they are may be of interest. The former is unnecessary for most blogs, and I can satisfy my limited needs for the latter simply by storing snapshots for backup purposes.
This is not to say that I do anything that prevents webpage from working with version controlled material, I'm simply not going to assume any responsibility for explicit integration with a vcs - that's out of scope.
I considered whether I should pull in all the CSS that I find between the markdown directory and the root of the tree, and thereby put the 'Cascade' into CSS. This is an example of one of the many little design choices that can suck a lot of time out of a project. So I tossed a coin ( literally ), knowing that I could revisit this choice later if necessary.
I can do this because I'm both the 'product owner' and the developer. In fact, as a developer, I'd heartily recommend this approach to product owners - don't sweat the small stuff, if the answer isn't obvious toss a coin, get something that works, and see how it goes. This may even be Agile 🙂.
© Mark de Roussier 2021, all rights reserved.