How to make a blog with hugo, like this one!

Some time ago I stumbled onto the idea of “learning in public”. The concept is very simple, you write tutorials/blogposts/cheatsheets on what you read/study and publish it in a public place.

In a nutshell, the idea works because it “forces” you to explain concepts in a decent manner, and, like the Feymann technique, this leads to not only helping others but also helping yourself understand better the material. Basically, you won’t have some mediocre notes thrown around but a more decent document that at least at first glance can cause an observer to say “cool”.

Jokes aside, I like reading blogs, especially obscure blogs that do not have an audience in mind and are, precisely, written more as a testimony for the author himself than anything else. The articles found in this type of blog are usually short, technical, and target a specific problem. So, they are not very useful for third parties unless they specifically were searching for that problem, in which case they are invaluable (and a great way to connect with people).

In general, it’s a great way to push yourself and make the most out of your study journey and maybe leave a testimony of what you have done for people who will come after. I lost count of the times I found the answer I needed in an obscure blog among various ramblings.

It’s good for everyone, so why not?

If you want a more convincing post try this one.

This is in a sense correlated to the concept of “Digital Garden”

Think of it as a laboratory where your internal work and the evolution of research are displayed for public to see.

Three levels:

  1. Seeds: These are raw ideas. Personal notes.
  2. Trees: Grow your seed by forming new branches connecting related ideas. Write structured, concise notes to publish in your digital garden. One note = One idea.
  3. Fruits: This is the refined, publishable content. Essays, videos, or even a book at some point.

Get Hugo

You’ll probably find an infinite amount of tutorials on how to make a simple Hugo website, this is my take. I discovered that it’s not so trivial to set up everything correctly, especially because different themes work in slightly different ways. I hope that if you are in a similar situation to mine this blog post will help you fix your problems.

I won’t go too in-depth on the inner workings of Hugo because I don’t know them, and that’s the beauty of it. Hugo has been made to quickly deploy personal blogs, and that’s the approach the majority of people have with it. If you want more information, you can find it at Hugo. I’ll try to explain the fundamentals you need to make it work throughout the post.

Like with any modern software, you can find it in an easily downloadable prepackaged app in your distro of choice. You must have git installed to proceed.

Go here and follow the instructions for your distro. You must install “hugo-extended” and not the basic “hugo” package or else you might get errors with some themes (like the one used in this tutorial).

img1

Let’s create the blog

Position yourself in the folder you want to use, in my case I’ll use the “Document” folder. Create a new Hugo website and move into the folder.

hugo new site my-blog
cd my-blog

Initialize git and download your theme of choice from here. I selected this awesome one. Thank you Sidharth!

git init
git submodule add https://github.com/hugo-sid/hugo-blog-awesome.git themes/hugo-blog-awesome

img2 As you can see, the theme is awesome for real! Sidharth was so kind to include some example posts that will teach you some Markdown

You are almost done. If you explore the hierarchy folder you’ll find a confusing situation. You will have the same structure present in your root folder, my-blog, and almost identical inside my-blog/themes/hugo-blog-awesome. Also, some folders present in my-blog will be found inside my-blog/themes/hugo-blog-awesome/exampleSite.

It’s a bit of a mess to understand where to put things if there are different places with the same name. For example, Avatar.jpg has to be positioned in the asset folder, but which one? config.toml is in the theme folder, in the root you have hugo.toml, what is the deal?

The simple way to make it work:

  1. Put everything that is inside exampleSite inside hugo-blog-awesome. This will make your website the same as the example used for testing.
  2. Now the website will build (more on that later), but without the example posts the structure will work but not the content. The avatar will appear, so remember to substitute the file found in assets with your avatar.jpg. You should also copy the avatar and put it in the assets folder in your root (my-blog)
  3. Substitute the hugo.toml in my-blog with the config.toml file that now is in the hugo-blog-awesome folder (you have to rename the config.toml to hugo.toml). Remove the config.toml from the theme folder in case you have just copied it.
  4. To see the example posts copy the content of the content folder and put it in the my-hugo/content. Now you’ll have the exampleSite content in your blog. Remove the post manually (they contain useful info so you might want to read them before) and modify the About page as you see fit.

img3 Your avatar probably won’t be as good as mine but don’t worry the website will work anyway

Check That Everything Works And Make your First Post

Now position yourself in the my-blog. Build your hugo website with:

hugo server -D

Now your Hugo instance will be running at localhost:1313. Check that it works and that you can navigate the pages. It might be easier with the example posts. The -D tells Hugo to display also the draft posts. Now it doesn’t make any difference, but remember that when you add a post it will be in draft mode. To publish it, remove the “draft: true” from the header.

You can create a new post with:

hugo new posts/first_post/my_first_post.md

Modify the “.md” file as you want and see in the website your newly created post.

That’s it really. Now learn a minimum of Markdown and start blogging locally.

Blogging Online

If you want to publish your blog online, you have different possibilities. In a nutshell, what Hugo does is let you build a static website, put it in the “public” folder, and that’s it. To build public just write “hugo” in the root folder. If you have a hosting service at your disposal, you can use the content in public and automate the process of deploying the website comfortably.

I’ll explain the way you can do that with websites like Cloudflare pages and Gitlab pages. These services offer free hosting for static personal websites with seamless integration with Git.

First create a repo in your platform of choice (i use GitLab):

git remote add origin https://gitlab.com/<username>/<repo>
git branch -M main
git push -u origin main

As the page host, I will use Cloudflare pages. Log in to your account and go to Workers & Pages > Create an application > Pages > Connect to Git. Open Set up builds and deployments and select your git repo, providing also your production branch (default should be main), build command (hugo), and build directory (public). You can find in the previous section why these choices are being made for Hugo. Or you can select the correct template from the drop-down menu and autofill the fields.

Save, deploy and you are done. Happy blogging.