Static Site Generator or Content Management System?

Development

Can a static site generator (SSG) be more accessible than a content management system (CMS) to someone without Web development experience? And should we use an SSG instead of setting up something like WordPress?

For those who don’t know, a static site generator is essentially a program that compiles a directory of text/Markdown files into a Web site that can be hosted on any Web server. Its core function is to convert Markdown to HTML. There are a few advantages to this: Most developers who just want a static site just need a Web server without a stack of other things like PHP, ASP.NET, MySQL, etc. that’s required for a CMS. Also, SSGs will automate the painstaking task of manually crafting HTML pages (if anyone still does that). With an SSG, we’re also not dependent on the CMS itself to modify or copy the content of our sites (this is a huge plus for me).

According to Kev Quirk, static site generators (SSGs) are easy to use, but only for those with considerable development-related expertise, and particularly experience with things like Continuous Deployment, version control, layouts, frontmatter, etc. Florens Verschelde goes further in making it seem that every stage of getting a site deployed this way presents a barrier for the non-developer, especially if it involves using the command line. I really don’t think this is true for all, or even most, static site generators. Setting up the foundations of a blog, with the right SSG, is entirely doable for anyone with an afternoon to spare.

And I think it’s a bit dishonest to say that static site generators are difficult to use, if they’re being compared to managed services, such as WordPress.com, that are already installed, configured and hosted by a third-party. A fairer comparison would be a manual setup of both, either on a local machine or a VPS.

Let’s look at what’s actually involved in getting a site/blog set up with an SSG:

  • a) The user runs a command or two in a terminal to get the SSG installed, perhaps with a template. This only needs to be done once, and for most SSGs, there are guides to this.
  • b) A Web page or blog post is drafted as a Markdown document, which is essentially just a text file with a few special characters for formatting.
  • c) We typically use just one simple command to compile the directory of Markdown files into a Web site.
  • d) The files generated can be uploaded to a server, and there are a variety of ways to do this. It can be as simple as uploading the files through a Web interface for a basic hosting account.

So, it’s not difficult, but it is cumbersome when we’re getting started - I’m writing this as someone who did struggle a bit with customising a Jekyll site. A non-developer will, however, run into problems when trying to incorporate search features and custom layouts for specific pages. Finding the right SSG and theme that provides search/tagging features and lends itself to customisation is hit and miss.

But which SSG to use? That’s an important question.

My experience is mainly with MkDocs, which is my SSG of choice, and I find it much easier than Jekyll and Hugo (both far more commonly used) to get a site/blog set up. All I needed to do was install Python and use that to install MkDocs itself. If, instead, we choose to install MkDocs Material as the starting point, we get a nice theme and a good set of plugins (the search feature especially).

Whenever I add a new post, I simply create a new Markdown file in the directory, add a reference to it in the configuration and run ‘mkdocs build’ in PowerShell. Again, there are various ways to get the site published.

There are a few other things to consider.

Dependencies 

Certainly, a Content Management System is very easy to use, if we’re registering with a ready-made service like WordPress.com or Blogspot, hosted by a third-party, and we’re happy with everything being on someone else’s server. If, instead, we need to develop, preview and test a site on our own laptops/computers, though, several things need to be installed and configured: the CMS software, PHP, the database server, the database itself, and perhaps a few other dependencies. The only exception to this I’ve encountered is Publii (which is, strictly speaking, a static site generator).

Being a database application would mean, of course, that the content isn’t very portable - posts could only be edited through the CMS, unless we’re in the habit of exporting and importing them whenever we want to use another editor. We would also need a method of migrating the content a live server to make it public.

A static site generator, on the other hand, is mainly a stand-alone thing, all its dependencies can quickly be installed on any machine, and all the files can be copied and modified in pretty much any editor.

Markdown

Quite a few people I work with use Markdown for pretty much everything. Markdown is dead easy to learn, it can be created and modified in any editor, and there are 1001 applications that will render it in multiple formats (even PDF) - this makes it highly versatile. I can readily copy any Markdown file into my site directory if I wanted it rendered by MkDocs as a Web page or a blog post.

Deployment Process

The deployment process can be very straightforward, and it does become a matter of habit. Again, mine is simply to run a build command and upload the files over S/FTP, and there are desktop applications, like FileZilla, for that. Other options include uploading the files though a Web interface, or using GitHub to publish the changes.

Customisation

A good Content Management System is going to provide some feature that enables the user to add custom CSS rules to override the defaults. An SSG, on the other hand, will have a CSS file somewhere in the site directory, and the method of overriding it is going to vary depending on the setup. Either way, tuning the site appearance will involve the use of the browser’s developer tools to determine which CSS rule needs to be changed. In both cases it’s time-consuming, for someone with a very specific idea of the colour scheme and appearance.

Modifying the layouts is a little more involved, and usually entails creating a template file containing HTML with some embedded Python/Ruby code, then declaring it in a configuration file - this appears tricky, but I have come across Content Management Systems (e.g. OpenCart) for which I needed to create PHP modules in order to make even minor changes to the appearance.