I’ve done it before and it looks like I’m doing it again. It’s the right time to move my personal blog from WordPress to a static site for simplicity, portability, and performance.
My objectives for this move are:
With that in mind, I knew I wanted to use a static site generator and write in simple Markdown. So I needed to pick the right static site generator for this project. My experiments, so far, have been with Jekyll and I like it. But the fact is that Jekyll is a mature system with few updates and many themes that are no longer maintained, or are being maintained only for backward compatibility with the old GitHub Pages workflow.
This lack of updates to the system and the themes lead me to consider a few other popular static site generators.
I’m trying out Hugo. I don’t want the complexity of an application framework for a static site blog, and learning Go might be interesting. It should take care of my performance, security, and convenience objectives. The portability part will take a bit of work, and discipline, on my part.
Markdown is an inherently portable document format. But plain old Markdown doesn’t offer more than the very basics in formatting. Not even Definition Lists, Fenced Code Blocks, Tables, or Footnotes. These features, and others, are implemented in the many Markdown alternatives such as kramdown (Ruby), CommonMark (PHP), markdown-it (JavaScript), and GoldMark (Go).
And that’s the problem. The Markdown alternatives don’t all agree on syntax and features. Floating an image to the right with a caption requires using either shortcodes, plug-ins, or specialized syntax. None of that is very portable.
The good news for flexibility in image display is that all the Markdown alternatives respect plain HTML. That let’s me copy and paste a block of code (or, even better, create a snippet) and just edit the image path, to float left or right, and to add a caption. Maybe change the width.
<figure style="float: right; width: 50%; margin: 1em 0em 1em 1em">
<img src="/images/image.jpg" alt="Alternate Text" >
<figcaption>Caption</figcaption>
</figure>
Making the caption look ‘right’ only takes a little CSS in the theme.
figcaption {
text-align: center;
font-size: 0.85rem;
}
Coding for portability includes what goes in the YAML front matter. For example, some static site generators (or their themes) use an excerpt marker in the text (<!--more--> or <!--excerpt-->) and others expect the excerpt to be in the description: or maybe the summary: field in the front matter. So articles I’m writing now use both the summary and <!--more-->; the comment will just be ignored by generators not using it.
I may end up just using the front matter for excerpts because that might actually be the ‘standard’. Before I’m sure, I’ll need to do more work in learning how other static site generators use YAML front matter in hopes of finding what really is ‘standard’ and what will be a portability problem.
So far Hugo is working out pretty well. The learning curve is a little steep for me, not knowing the Go Template Language, and Hugo’s documentation doesn’t help – it’s broken into so many little pieces that finding what I want is better done with a web search. But most of the available themes are well maintained and several of them are very nice. Right now I’m working with Roadster which is a fork of Mainroad (because that author no longer maintains it). Hugo is updated frequently and can break themes, so maintenance is important.
Hugo is indeed very fast generating my site. Jekyll was pretty fast, but Hugo is almost instant. Its development server is very good at seeing file changes and updating the browser which makes tweaking things so much easier. I like it.