loading...
Cover image for Hugo: an almost ideal static website generator

Hugo: an almost ideal static website generator

stereobooster profile image stereobooster Originally published at stereobooster.com on ・2 min read

I use Hugo for my blog. For me, as a developer, this is an ideal experience.

  • I can edit markdown files in my editor of choice.
  • I can open-source it, so people can send PRs with edits (or translation of articles).
  • I can host it with static hosting. I use Netlify, but now, or Cloudflare + S3 would work as well.

For me, the concept of Hugo is very clear because it is the same idea as in Jekyll. Implementation is a bit faster, but it is not that easy to extend. In the case of Jekyll, it is easy to add a plugin. In the case of Hugo, you need to recompile it. Trade-offs - as always.

I use Parcel to bundle frontend assets. I use a bit of JS and PostCSS (instead of traditional SASS). I fine-tuned the performance of the theme. I configured very basic styles - nothing fancy but works for me.

I'm almost happy...

But

Templates

It is always a problem for me to write some advanced logic with declarative template language. I'm not saying that Hugo template language is bad. I'm saying all templating languages that I've worked with have this issue. I worked with Smarty, Twig, handlebars, etc. - I don't remember all of them it was some time ago.

In this sense, JSX, PHP, erb is easier to work with because they are not declarative. I have nothing against declarative DSL (domain-specific languages), but they typically made with some specific use cases in mind and as soon as you cross this line it becomes clumsy. Try to work with graph data in SQL - yes there are ways, but it is the worst use case for SQL.

In Jekyll, it was possible to write custom ("liquid") tags in ruby, but in Hugo, I need to use templates for custom tags.

It is hard for me to find the logic behind this language, so I end up searching the internet for example and copy-pasting.

As a result, I have now "image" tag which breaks if I use more than one instance of it on the page and I have no idea how to debug this. I will eventually figure out, but this is annoying.

Possible solution: maybe instead of templating language use DSL based on flexible language, for example ruby and lisp.

ToC

I can't customize the table of contents. Table of contents uses h1 for root-level elements, but instead, I want to use h2, because h1 is for main page title (I try to follow semantical structure).

Can't override markdown tags

It would be nice if I could customize markdown output, for example, if I could replace default image ![](./image.jpg), with my custom implementation, which would generate responsive images and provide width, height. Instead I need to use {{ < img src="image.jpg" > }}.

What do you think about Hugo?

What features do you miss? What feature do you like? Do you know some interesting tricks?

Posted on by:

stereobooster profile

stereobooster

@stereobooster

Hello, I'm a full stack web developer. Follow me on Twitter!

Discussion

markdown guide
 

To me Hugo is an almost ideal SSG since it supports writing with Asciidoctor unlike with Jekyll where you have to install a plugin for it. With the heavier feature set of Asciidoctor and the performance of Hugo, it makes for a fun writing experience.

I said almost ideal since it doesn't support the native front matter of Asciidoctor.

 

Yes, and this also allows creating your own tags easily with plugins: github.com/cirosantilli/cirosantil... although replacing existing constructs is not supported yet: github.com/asciidoctor/asciidoctor...

 
 

You should try out Gatsby.js. Static site generator based in React, also amazing performance.

 

I don't have free week to configure it

 

I use it on my site github.com/theodesp/codethat

It's true, that somehow the custom shortcode tags are not ideal but if you have an HTML theme it's easier to convert it with Hugo than Gatsby.

 

If you want a custom site or section ToC then you can use a section page template gohugo.io/templates/section-templa...

If its single page ToC you need to customize then use a custom list template gohugo.io/templates/lists/

 

I miss template Inheritance, just like in Nunjucks (11ty).