Writing HTML in HTML

Published on 2019-06-19

I’ve just finished the final rewrite of my website. I’m not lying: this is the last time I’m ever going to do it. This website has gone through countless rewrites – from PHP to WordPress to Jekyll to multiple static site generators of my own – but this is the final one. I know so, because I’ve found the ultimate method for writing webpages: pure HTML.

It sounds obvious, but when you think about how many static site generators are being released every day – the list is practically endless – it's far from obvious. Drew DeVault recently challanged people to create their own blog, and he didn't even mention the fact that one could write it in pure HTML:

If you want a hosted platform, I recommend write.as. If you’re technical, you could build your own blog with Jekyll or Hugo. GitHub offers free hosting for Jekyll-based blogs.

Now, there's nothing wrong with Jekyll or Hugo; it's just interesting that HTML doesn't even get a mention. And of course, I'm not criticizing Drew; I think the work he's doing is great. But, just like me and you, he is a child of his time.

That’s why I’m writing this blog post – to turn the tide just a little bit.


So what are the benefits of writing HTML in HTML?

There’s one less level of indirection.

This point is simple, but hugely important.

Using a static site generator means that you have to keep track of two sources: the actual Markdown source and the resulting HTML source. This may not sound too difficult, but always having to make sure that these two sources are in line with each other takes a mental toll. Now, when I write in HTML, I only have to keep track of one source.

Further, you actually need to have your static site generator installed. Again, not a huge thing, but if you often switch between different operating systems, this is yet another chore. With HTML, you just need a web browser – which, if you’re creating a website, you need anyway!

Finally, you constantly have to work around the limitations of your static site generator. Let's say you want your site to have a specific directory structure, where pages are sorted under various categories. With Jekyll, this is practically impossible, and even though you technically can get it working if you really try, it is only through much effort and with a source code that is organized much more unintuitively than if you just wrote it directly in HTML.

These seemingly small things tend to add up, and when you know that there are three or four extra things you have to think about before you write another blog post, there’s a higher threshold to start writing.

And that’s something that I’ve noticed: with nothing but pure HTML, there’s is no threshold. When I used a static site generated, I always had to do a dozen small things – start the auto-refresh server, research how to do something – before I was ready to do anything. Now, creating a new theme, a new post, a new page or even a new site requires no setup – I just open up a HTML document and start writing!

So what’s the catch? There has be some reason why people don’t write their personal websites in pure HTML. Well, it’s simple:

HTML is unpleasant to write.

This is the only real reason. And it’s true – HTML is a pain to write! But the solution, I argue, isn’t to use other languages that are then trans­lated to HTML (we’ve seen above how many problems that causes); the solution is to use better editors.

The best HTML editor I’ve found is actually the WYSIWYG Composer part of Seamonkey. As long as the source is HTML 4.01 (which, for a personal blog, is surely sufficient), it can edit any HTML document. It’s what I’m using right now to write this post, and despite its age and a couple of quirks, it works really well.

Screenshot of SeaMonkey's
                  Composer.

Another very promising alternative, which isn’t WYSIWYG, but more of a WYSIWYG editor, goes under the name HTML Notepad.

If you don’t want a WYSIWYG editor, I’m sure that modern IDEs have reasonable support for HTML.

In any case, once you start writing a post, you’ll notice that it actually isn’t so bad, as long as you have an editor that is more modern than vi (no offense to vi users – I use it as my main editor myself).

Doesn’t this mean that I have to type a bunch of boilerplate every time I create a new blog post?

My simple answer is: just copy it. My more advanced answer is this:

  1. Make blog posts and pages self-contained – in other words, have each post or page reside in its own folder, with its own scripts and stylesheets.
  2. When you want to write another post or page, copy the folder of an already existing post or page and edit it.
  3. If you find the previous step too much work, write a shell script that copies the directory and removes the old content for you.
But how can I then keep the style and layout of all my posts and pages in sync?

Simple: don’t! It’s more fun that way. Look at this website: if you read any previous blog post, you’ll notice that they have a different stylesheet. This is because they were written at different times. As such, they’re like time capsules.


In summary, I don’t think this post will convince everyone – and it’s not written for everyone. It’s written for those who have found themselves in the same situation as me: regularly rewriting their website, fighting with their static site generator. For these people, I think pure HTML is the best choice.

Response

I got a great deal of response on Lobste.rs, and I thought I could include some of it here. Thanks for all your comments!

j11g:

One benefit of using a CMS or site generator is an automatic RSS feed. Hint: this blog currently has no RSS feed ;)

As a response to this, I’ve cobbled together a PHP script that automatically generates an RSS feed from my index page (I chose RSS specifically because it is less strict than Atom). As such, I now have an RSS feed, and I still don’t have to worry about generating anything myself.

hyperpape:

Case in point about the downsides, the cv link is correct on the author’s homepage. It is not correct on this page. That’s an easy mistake to make, and I’ve definitely made versions of it. However, it’s much more pleasant to fix when you can fix it everywhere by updating a template.

I fixed this with a simple sed command:

$ sed -i 's,href="cv",href="../cv",' */*.html

jzp:

I love this. It’s sort of opposite to my own view where all of my writings are in plain text files, allowing me to do things that would otherwise be crushed by the layout. I think the “copy and alter”-method of authoring is genius in a world where everything is anxiously polished and uniform. To let the progression be a part of the published material is just beautiful. And exceedingly rare.

Apart from being really nice, this comment summarizes my final point perfectly. Thank you!