Learning Hugo
@ ヨハネス · Wednesday, May 6, 2020 · 5 minute read · Update at Feb 3, 2021

Attempt #23 to create a Website…

Yeah, so as usual, there never is any time for creating my own blog / portfolio. It’s the same for everybody. Unless you never work and have no hobbies whatsoever I guess.

Anyway, lets cut to the chase. My idea was simple. Instead of focusing on making the Website, I can just focus on the regular documentation and knowledge building I do all day every day and get that organized at the same time.

All it needed was some not-to-ugly theme and easy to use CMS.

hugo seems pretty developer friendly, so lets give it a shot

this website is far from perfect, yet, but lets think about some things it can do.

  1. we can tag articles for easy search later
  2. we can deploy for free to netlify
  3. it uses markdown which, imho anybody should learn
  4. hugo specific markdown cheatsheet

Anyway from now on, my posts will probably be more in a TLDR fasion

documenting all my failures is such a great idea

this guy is the creator of the theme, dropping for reference recurring theme

source on github

actual website



  • download and install hugo deb package (ubuntu ppa is super outdated, didn’t even build the theme yikes!)
  • initialize the repo and start a hugo site by running hugo start myreponame
    • create the theme you want to use as a submodule in the themes folder
    • make sure to look at the themes instructions about configuration
  • start hugo dev server hugo server it will auto build and reload the website nonstop, super convenient
  • create a first post hugo new path/to/post.md the path can determine categories, I think , I am not sure about that stuff yet
  • push the repo to auto build, やった!

and that is were we stop for today ~

Post Bundles

I thought it could be difficult to keep track of media that could be added to posts, if they are all in the static folder. It would require a lot of care to not mess everything up in the future. But so did the hugo developers. instead of naming posts directly yadayada.md we create a structure like

hugo new /path/to/post/yadayada/index.md

Than we can collect images and files for that post in the yadayada folder and use a pletora of shortcodes to access them.

I added the image shortcode by creating the shortcode folder in the layouts folder and adding img.html file. let’s test it here.

{{< img "*shrug*" "Every day something new!" >}}

Still not working 100%, guess something changed in the API, but to lazy to look into it now, I don’t really need this functionality yet.


So, some things of this theme are very nice, others not so much. How to deal with it? Luckily, the Hugo-Developer is smart and it’s pretty easy and similar to how Rules are applied in CSS. First the theme gets parsed, than anything in the main page. As a result, one can define new css rules in his own static/css folder to overwrite the theme wherever necessary.

In my case, the problem was, that when switching the theme from light to dark, the emphasis on code blocks was pretty much lost. Also the default code blocks seemed pretty weak, very hard to see. By default their behavior is defined in github-markdon.css.

This guy explains pretty good whats going on here

Long story short:

  • either create a partial with the cusomization needed
  • or just copy a css file that is used by the theme and edit it.

I am going for the second version, as it involves less files and my theme seems to be pretty straight forward about it (most stuff I care about is happening in github-markdown.css)

I just changed the alpha value on the class .markdown-body code to be a little more aggressive and added this css right after it.

.ui.inverted.segment code {
  background-color: rgba(41, 3, 44, 0.7);

It means, that if we are a code block and a child of an object with the class ui.inverted.segment, we get new rules. And as it happens, that’s what the body of my Posts turns into when pressing the night mode button. However, this also messed with big code blocks, so we needed another override defining the same parent class, but dropping the background-color attribute again. I set it to the same attribute the code gets when inside .markdown-body pre code, which happens to be transparent.

.ui.inverted.segment pre code {
  background-color: transparent;

Custom fonts

Fonts are an important part of web design.

Google knows this, too, and made it very easy to add a variety of fonts.

It so easy, many people use it, and Google can track everyone. Thank you Google…

 /* fuck google
  * @import url(https://fonts.googleapis.com/css?family=Lato:400,700,400italic,700italic&subset=latin);
  @font-face {
    font-family: 'ubuntu_r';
    src: url('/font/Ubuntu-R.woff2') format('woff2'),
     url('/font/Ubuntu-R.woff') format('woff');
    font-weight: normal;
    font-style: normal;

So just replace a few sections of some more stylesheets and be done with it.

Here is an example what happens if using a font, that is not available to the used browser.

Important to note is, even thou the folder “font” is in my static directory, hugo resolves to the base address of the server. It cost me 2-3 grey hair before rtfm.

Custom classes and IDs

This is a static site, but at some point, for this, or other projects, I definitely want to add some javascript and try out serverless designs. So, it is important to get some control over your page, like IDs or classes.

As it turns out, this is very easy. Just add curly braces behind the element, and define #myid or .myclass

# My cool heading{.specialHeadingClass}
a dynamic paragraph{#Id_find_by_JS}
also, html can be written directly, *however it will not be parsed using the markdown rules*

To enable this feature, it is necessary to allow unsafe rendering in the hugo configuration file
      unsafe = true

And that’s it

or so I thought, but I don’t know yet how to add it to regular paragraphs to be honest. まいっかー

Also thank this guy for the cool buttons on the code blocks!

Social Links