Moving to Hugo

For a long time I’ve been wanting to Migrate my blog system from Pelican to Hugo. One reason is that I had enough with python virtual environment breaks every 3 months. Another motivation is obviously I would like to replace Python with Go in my life.

A long time ago I followed Go tutorial for getting started, surprised by its syntax tidiness and similarity to Python, and it is way faster. But soon I found out it would be one of this thing I learned for a weekend and forget all together, since I don’t have any projects I would use it actively. Now after one month of procrastination, I finally pieces ALMOST everything to reproduce my old blog. Time for a summary.

The Hugo content folder.

I am so lazy these days that I want just to get things done without knowing all the details. Hugo renders the site in the same structure of your content folder. So if you have /content/blog/ it would be rendered as /blog/first-post/index.html. Hugo comes with some basic content types, one of those is the blog. So if you throw all your posts in the /blog/, they would be treated as blog.

Hugo by default uses Markdown as the content type, you can switch to other ones if you prefer, I would actually like ReStructuredText, but RST comes with many dialects like Lisp, so the ones I used with pelican won’t automatically work for Hugo.

Pelican uses a special syntax for linking your assets or ![euler angle]({static}/imgs/eulerangles.png), it will points to the static path your stated in your and. You can also points to your other posts using {filename}/ syntax, then pelican will translate the .md into .html during the build. Okay, Hugo don’t have this thing.

Hugo reflects the rendered site just like the way you arrange your content. So if you want to point to one of content, if will just be /blog/content/, note that you don’t need specify the markdown here. Or if you prefer shortcode you can do that as well.

The asset links is a kind of the same, but here Hugo don’t copy images inside content to your site folder. Instead, they are accessed through static folder, During the rendering, Hugo copies those items in the root folder. So if a image is in /static/sample.jpg, you will need to access it through ![image](/sample.jpg).


This is the major part of the moving since a blog is not the same without its proper theme. Luckily the Attila has a port for Hugo, the original Attila is far from what I can merge from so I think I will stick with this one for now.


Some of my blogs uses MathJax for rendering latex equations, it was one plugin in Pelican here it takes a bit more effort, basically I followed Geoff Ruddock tutorial for setting it up. But note that line-breaks are not implemented by Mathjax3 at the moment, so you need to fight with markdown syntax manually. The markdown parser runs first so \\ will result in single backslash, then mathjax only sees one backlash it won’t be treated as line breaks. So you need to escape them with \\\.


Shortcode is the Hugo’s way turning your markdown into its own dialect. Then things becomes very convenient but not portable anymore. Can’t blame it though, before I was using fluid tags from pelican. Every one uses its own dialects now.

The function I need is graphviz. It is rendered by gravizo. Paste the following code if your shortcodes folder then you can start using them in your posts.

{{ $title := "Diagram" }}
{{ if .IsNamedParams }}
  {{ with .Get "title" }}
    {{ $title = . }}
  {{ end }}
{{ else }}
  {{ with .Get 0 }}
    {{ $title = . }}
  {{ end }}
{{ end }}

    src='{{ .Inner }}'
    alt='{{ $title  }}'
    <figcaption>{{ $title  }}</figcaption>


Overall it is not as pleasant as I expected, or was it worth the pain? The big plus here is the rendering time. It used to take 8 seconds in pelican now it renders instantly.

comments powered by Disqus