Migration from Pelican to Hugo
I recently migrated my blog from Pelican, a python based static site generator, to Hugo, based on Go. Why? Pelican is good, flexible and has many capabilities, but there were some updates that changed the behavior underneath, some themes got abandoned, and it required some time to have it work again as I want. Hugo means starting from zero, but it is well maintained and documented and, although I had to invest some time, I am now in a live platform, while Pelican seems to be going less and less maintained and used by the community.
But why a static site?
Aren’t there very good blog and publishing platforms there, with all sorts of features? Yes, they are, but I took a conscious decision based on some principles:
- I want to keep things simple. I don’t want to be maintaining a full blown site, with databases, plugins, content moderation, comment spam, captchas, etc. Internet is full of threats, bots and other nuisances, and I don’t want to spend time fighting against them, configuring some obscure feature that looks cool, or doing more sysadmin time right now.
- I want to own my data and site. I want to depend less and less on third parties to have my data or having my platform closed for whatever reason. That means that, although there are platforms that simplify or make the maintenance process invisible to the user, I have decided it does not work for me now.
- I’m a nerd, so I like to have all the workflow under my control :) With my workflow (emacs, orgmode, ox-hugo, and hugo) everything from the hosting to the publishing, configuration, content creation, etc, is under my control. And that is satisfying, open source, and as much plain text as possible.
Migration
Changing from Pelican to Hugo is not that hard, but requires some tweaks.
Site config
Different styles, but same concepts underneath (at least, in my opinion).
Pelican uses just a python file to configure the site, and knowing python helps to configure it.
In Hugo you can choose between three plain text formats:
- toml
- yaml
- json
Since they are text formats, they don’t really depend on your knowledge of Go to configure them (but I suppose it helps).
The Hugo config file for the site is documented here, and you can see you can control a lot of options there.
Initially, I just configured the site title, author, and theme. Later, I had to modify the site config and add the particular theme tidbits.
Themes
First thing that you need is a theme. And I mean it. It seems, to the best of my knowledge, there isn’t a default theme. You cannot just create a new site and start playing. You need to deploy a theme to start serving, even in dev. And themes are wonderful, but each one has its config quirks. So read about the themes, pick one that catches your eye, read the documentation, and experiment with it until you are satisfied. The bright side is that you have lots of themes to choose from. The not so bright is that you will find some functionality is missing in the one you like the most, but such is life.
Also, some themes have convoluted options that are not always clear until you experiment with them.
I chose the LoveIt theme, and copied huge amounts of code from the theme config to the site config and started changing values until I got a good feeling. Please, read the documentation of your theme to learn what you can do!
Content migration
Content migration is not that hard, as both share the markdown format, but you will need to adjust some properties in the headers, usually just by name, as much of them share the same underlying functionality.
What is different is how the files are served and organized. I usually want to have a subdirectory for each category I have. For example, if I have the category “blog”, I want to serve those pages as <root>/blog/page.html. For that, I had to read what page bundles are in Hugo, and how to use them to organize my work. But, as always, you can choose your own content management.
Deployment
Pelican is far better than Hugo here. Pelican asked a lot of questions when creating the site, and many of them were related to how you wanted to deploy your files to your site. Then, it created a makefile with simple commands to create the content and upload your new files. It was simple and integrated in the framework.
Hugo does not do that. Although there is a deploy subcommand, it only works for some cloud providers.
I had to create my own script to do that, but you can find many examples over the Internet, such as this one.
Summary
Overall, the migration takes some time to adapt your site to your preferred theme and config, and depending on the number of posts you need to migrate, it can be quite cumbersome, probably needing to help yourself with some scripting.
I think it is worth the effort but, as always, your mileage may vary.