TLDR:

FINALLY! I’ve moved away from the old dreaded wordpress blog, and have migrated to hugo! I wanted to document a few things for myself/ohters going through this process.

HUGO is beautiful

I want to take a moment and thank the creators of hugo! Its honestly a great web development platform and alleviates the pain I have always hated in website development:

Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.

I’ve gotten really adept with markdown note taking in my classes in grad school, and I love that I can use markdown to format my blog in easy, quick edits, locally on my computer. Plus, the website is EASILY customizable and modable to my liking, with straightforward templating that is quick to understand.

This post will discuss my transitions from wordpress into hugo, and show the journey along the way.

Hosting & Wordpress woes

Previously this blog had been hosted via aws linux instance running wordpress, which at the time was fun to setup. I’d never hosted any service online before, and manually going about the process of garnering an aws ip, setting up my server, configuring wordpress, and creating my own piece of the internet was a good learning experience.

However, as I delved into using wordpress I began to feel the outdated nature of running a blog from wordpress. In order to update anything I first had to login. Once logged in, I had to use the painful editor to manually create my webpage, and if I wanted to do fancy code formatting I had to mess with painful code formatting plugins, that I hated wasting time on. Finally, writing was painful and arduous as none of the editors could support my vim key bindings/navigation I have come to know and love.

Plus, I’m a poor college student, and my free tier aws credits were running out…

So I had to find a format that had 4 qualities:

  1. Easy, painless management
  2. Beautiful, well formatted website posts, including code segments
  3. Cheap/Easy hosting
  4. As little javascript required as possible

I’d heard from friends about jekyll, but I found out that was somewhat based on ruby, and I’ve never liked that language. To chaotic, and unorganized for my taste. In addition, I don’t really enjoy the look/feel of jekyll based websites. Something has always felt off/displeasing.

However I wanted the power of this “static site generator”(SSG) paradigm, without the hassle of having to understand ruby. I like to understand how my tools work, if I can’t understand it, or its in a language I find abhorrent, this is a huge turn off.

I’ve been partial to go for a while for its interesting combination of C like low level control, python like scripting power/garbage collection, so I wanted to see if there was a go “SSG”.

Turns out hugo was a gold mine, and I’ve ben in love ever since.

hosting hugo:

Hugo’s quick start page shows all the awesome benefits of hugolink: “Speed, CMS, templating, etc…”. However, I needed somewhere to host it.

A friend had referred me to gitlab, so I wanted to checkout their “Gitlab Pages” service. The service is awesome and for FREE lets me do the following:

  • setup TLS certificate with lets encrypt
  • build hugo automatically using their built-in Content Integration (CI/CD)
  • use SSG CMS (i.e. file based folder hierarchy
  • sync everything through a git repo

All these features are available on their free tier platform!

So i followed the instructions here to move my domain over to gitlab pages and setup a hugo repo under my gitlab account: link.

I think gitlab is really underrated. It has a beautiful, straight forward interface, supports FOSS development, and has a very active development team. Many of the features they offer are forward thinking and easy to use/setup. They deserve more recognition for their product, as I had never heard of them until a year ago.

Anyway, with gitlab repo all setup under my mastermjr.com hostname, Now I needed a theme!

picking a theme

I settled on the ghostwriter theme that I modified a little to suite my own needs. It fit all of my requirements:

  1. Easy, painless management
  2. Beautiful, well formatted website posts, including code segments
  3. Cheap/Easy hosting
  4. As little javascript required as possible

Except I found out the hardway, 4 was not met. Unforutantely the theme was still using highlights.js for code highlighting, which while looking good, was hard to update for future bug fixing and setup/configure how I wanted. In addition, hugo has this wonderful feature builtin called chroma . It does all the syntax highlighting locally with the chroma go tool creating it with CSS! The tool is even inspired from pygments, which I’ve used before for latex code formatting and I love it! One quick javascript complaint: It may be that I’m not a javascript developer, but I find many things involving javascript development to be painful taxing and wasted effort.

So I decided to edit the ghostwriter theme (more to follow in a future blog post), and personalize it for my tastes. One annoying dependency this theme has is on the npm/yarn management tool to control the styles.scss file. For those that don’t know scss is short for a sass css file. (Scoth.io is a website I’ve used in the past for understanding web-dev jargon/tools, and I really like their content. Its well formatted, and easy to follow/read.) While this sass setup is a really neat tool, I despise using node as it involves more javascript tom foolery and extra requirements for installation/adoption. In the future, I will publish my similar theme that removes this dependency for changing the css sytles/colors. This change will be a requirement before I publish. (go has a tool to do this link I discuss briefly at the bottom).

Quick edit notes for those interested in what I changed:

  • I removed the links to javascript highlighting in the layout templates /layouts/partials/header.html and /layouts/partials/footer.html
  • I updated the colors in static/style.scss using their yarn publish setup in the readme
  • updated the config.toml to yaml and set the appropriate values

fixing code formatting to monokai:

I also added the following blurb to setup chroma to markup with monokai font:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

## code
markup:
  highlight:
    codeFences: true
    guessSyntax: false
    lineNoStart: 1
    lineNos: true
    lineNumbersInTable: true
    noClasses: true
    style: monokai
    tabWidth: 4

A note on colors:

I used a few of the following tools for updating and picking colors:

Transitioning

This script was ultimately my life saver: https://github.com/wooni005/exitwp-for-hugo However, it failed to do a few things for me:

  • properly convert my code blocks which where in weird bracket format from my old wordpress plugin
  • convert hyperlinks from the old wordpress urls
  • the code blocks were terribly formatted

This transition for these two points was ultimately a nights worth of troubleshooting, but luckily the new site looks much more clean in my opinion and I really like the color/code formatting. In the next sections, I’ll document my frustrations and solutions to these two problems, along with some other hiccups along the way.

code blocks

Unfortunately, I found no easy way to change these code blocks over, as my formatting was very inconsistent while I frantically wrote up my blog posts. It would have taken me far more time to write a smart regex/python parser to fix my markdown posts. So I went through and spent about an hour removing the old annoying brackets and putting in either go-like formatting short-code or just markdown ``` code blocks.

Luckily my blog at this time was super short (still is), and using some vim/command line fu, I was able to go in and edit each code block so it looked nice

I cheated and used a shortcut where I setup the files under my static site such that the url is the same, which involved NO editing. (i.e. I created folders under /static following the structure: `/wp-content/uploads/[YEAR]/[month]/[NAME].png'

The issue is it has this weird backwards compatibility issue. However, maybe I’ll fix this in the future? only time will tell.

Pipes and SASS/SCSS:

Hugo actually supports SASS/SCSS files with hugo pipes link!

This utility allows unix-like piping in template commands, such that you can string together function calls to enable powerful queues all inside templates that create webpages.

My example I used was the simple scss-sass functionality. Using this simple example, I was able to have pipes process my scss file, and create the css files for my website based on the ghost writer theme:

  • I added into the files: (/layouts/partials/header.html ) the following lines, changing the style sheet link at the top of the header.
1
2
3

    {{ $options := (dict "targetPath" "style.css" "outputStyle" "compressed" "enableSourceMap" false ) }}
{{ $style := resources.Get "sass/style.scss" | resources.ToCSS $options }}
      <link rel="stylesheet" href="{{ $style.RelPermalink }}">

This removes the whole need for having the yarn install process! However there is one caveat, I had to ensure the hugo version included the extended tag! link

installing with extended tag:

I like to git clone and then go install --tags extended, to install hugo. If you’ve never used go before, their documentation has good resources for install go tools from source: link

The other step that is needed is to make sure to git checkout [release-branch], the newest release version! You can check that from seeing the releases tab in hugo’s github page

FavIcon Generation:

Last but not least a useful website to generate favicons from text, which has let me develop a favicon based on my chinese name: “荣富”。

LINK

Conclusion

I’m really happy with hugo and have found it pretty intuitive to get my website up and running. My goal with this website was a minimal theme that would be easy to maintain and modify, and run with zero javascript.

This transition was in periods of short bursts over the last 6 months and I’m really happy with how it has turned out!

My one regret is that hugo has this javascript: livereload.js that it loads in during compilation. Theres probably a way to disable this, which I will research in the future.