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/first-post.md 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.
Links to assets.
Pelican uses a special syntax for linking your assets or , it will points to the static path your
stated in your pelicanconf.py and. You can also points to your other posts
using {filename}/otherpost.md 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
.
Theme.
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.
MathJax
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
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 }}
<figure>
<img
src='https://g.gravizo.com/svg?{{ .Inner }}'
alt='{{ $title }}'
/>
<figcaption>{{ $title }}</figcaption>
</figure>
Summary
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.