Why I switched to static HTML generators

The Beginning

This Blog started its life a few years ago. At the beginning, I was using DokuWiki for writing and editing. This was good, but I was very limited by the provided editors and markup. So I came to the point that I needed something else. And you will of course ask "what else"? Well, for a Blog, there is a very popular answer: Use Wordpress!

So I installed Wordpress on my web host, and migrated the whole content. The migration task was easy. But I spent a lot of time with decisions like "Which theme? Which plugin? What about SEO? I really spent too much time on this.

Wordpress was and is a really good content management system. Its WYSIWYG editor is useful for writing Blog content, and I could produce content very comfortable. Maybe Wordpress is the best Web CMS.

But, did I really need it?

The Retrospective

Well, did I really need a full blown CMS for my blog? Did I need fancy themes? Did I need the full complexity of Wordpress?

I sat down and thought about this. And here is what I really needed for this Blog:

  • An easy way to write and provide content

  • Support for all kinds of technical documentations like UML diagrams and code highlighting

  • A version control system for the content

  • Super fast content delivery to my readers

From a technical point of view, I realized that my whole content was static. It changed only when I added or modified a Blog posting. For this, I really did not need a dynamic CMS. I needed fast content delivery.

What I came up with

I realized that I do not need a CMS. I needed a more user friendly way of writing content. And I needed a tool to create my static content in a transparent way. And here comes a set of tools to play called "Static HTML Generators".

But before I could answer the question about the right tooling, I had to decide which format is best suited for writing my content. A very popular format was and is Markdown. But was this the right tool for me? Well, at work I used Asciidoctor a lot. And it turned out to be the right tool for me for writing Blog postings, as it

  • Is plain text with no vendor lock in

  • Has a clear focus on content

  • Supports syntax highlighting

  • Can generate all kinds of diagrams

  • Can be transformed to all kind of document formats, such as HTML, PDF and others

So I decided to use Asciidoctor.

Now, which tools support Asciidoctor as a content source? It turned out that most static HTML generator tools support Asciidoctor in some way. So had to narrow down my list of candidates. And the final candidate I came up with was Hugo.

Why Hugo?

There are other very popular static HTML generators available. The far most popular is Jekyll. I decided to use Hugo as it is fast and comes as a zero dependencies Go binary. Another point was the way Hugo organized the content source fit really well with by style of writing.

Hugo is fast. It is really fast. It is maybe the fastest static HTML generator available. But does this really matter for my use case? It turned out: not really. I use Travis CI to build my Blog every time I publish content to my GitHub repository. And from my point of view the generation speed does not really matter. If it is five seconds or twenty seconds, it doesn’t make a difference. It would make a difference if the generation would take minutes to complete, as this might trigger timeouts in Travis CI. The complexity of my setup matters more. And from my point of view is Hugo here a clear winner.

Benefits of Asciidoctor

Asciidoctor is a great tool for writing all kinds of technical and non technical documentations.

I have syntax highlighting with callouts

public class Test {
    public static void main(String[] args) { (1)
        (2)
    }
}
1This is the main method
2Here goes my complex logic

I have Asciiart for diagrams

I can use ditaa for diagram generation:

ditaadiagram

I have UML

And I can use PlantUML for UML drawings:

plantuml

And even in "hand-drawn" mode:

plantumlhandrawn

Final thoughts

I really love the Asciidoctor / Hugo combination. Now I can better focus on content. The whole dynamic CMS process is replaced by static HTML generation, which speeds up content delivery to the max and reduces potential security problems to a minimum. If you need advice to setup a Blog for yourself, Asciidoctor and Hugo are worth a try!

Loading comments...