Let's JAM: Building a Blog with Hugo + GitHub Pages + Hover + Smol (Part 3)

So far we have bought a domain, installed and setup hugo, setup our git repository, and setup GitHub Pages for hosting. In this final part of our main series, we’re getting to the least fun part: publishing. To get started, we’ll first go into our local clone of our repository and create a new post with the hugo new command:

cd theresa-tobias.website
hugo new theresa/my-first-post.md

hugo will create a skeleton for our new post with some basic information in the file content/theresa/my-first-post.md, looking something like this:

---
title: "My First Post"
date: 2020-08-16T11:49:00+02:00
draft: true
---

How did hugo do that? Well, it uses a post archetype into which it copies some basic information. In the archetype folder you will find a default.md that looks like this:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
---

As a title, it uses the filename, replaces all hyphens with spaces, and converts it to title case.¹ As a date, it uses the current date (obviously).

You will have noticed that we prefixed our post name with theresa/ to tell hugo into which folder to put the post file. This can be quite useful for sorting but it also has another added benefit: hugo has several levels of archetype files that it checks before defaulting to archetypes/default.md.² It will, in our case, first check if an archetypes/theresa.md file exists. Currently, it doesn’t, so let’s create one that is just for the theresa author:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
tags:
- tag1
- tag2
author: "theresa"
---

As you can see, we have added an author tag that always sets author: "theresa" for all posts created in the posts/theresa folder. Useful! We also add a template for setting post tags, just so we don’t forget when we publish a post.

Our post is only a draft at the moment, but let’s see what it looks like. For that, we’ll start the hugo development server with the -D flag:

hugo server -D

This starts a local development server at http://localhost:1313 that has all your posts, including drafts.³ As long as you keep draft: true, compiling your posts or using the server without the -D flag will not show the post. Anyways, this is what it should look like now:

Pretty cool, eh?! You can now add any text you want underneath the --- using standard markdown syntax and it will be compiled by hugo. Here is an example post:

---
title: "My First Post"
date: 2020-08-16T11:49:00+02:00
draft: true
tags:
  - tutorial
author: "theresa"
---

# This is a heading

## This is a subheading

### It's headings...

#### ...all the way down

Here is some standard text.
A linebreak is not a linebreak.

Two linebreaks are a linebreak.

[This is a link](https://jizzhub.com).

Here is an image:

![alt text for blind people](/theresa/image.png "here is a caption for the image")

When you want to put an image in your post, place it into the `static` folder in your hugo repository.[^1]

[^1]: this is a footnote

You can also use `inline code` using backticks or even multiline with syntax highlighting:

```python
foo = bar
```

You will see the compiled version immediately as the hugo server has hot-reloading enabled by default.

When you’re happy with your post, set draft: false and publish it. First, we must compile our website using the hugo command (don’t use the -D flag now) into the docs/ folder. Then, we will have to commit and push our files to GitHub for GitHub Pages to pick it up. By default, hugo will not delete the old docs/ content, which is messy when you want to delete a post. However, deleting the docs/ folder and recreating it with hugo will also delete the CNAME file that GitHub created for us to use our custom domain name for GitHub Pages, so we will have to consider that as well. To make this whole process easier for us, let’s create a Makefile so we can use the make command instead of typing everything out from memory each time we want to publish something:⁴

.PHONY: all

all:
	mv docs/CNAME ./CNAME
	rm -rd docs
	hugo
	mv ./CNAME docs/CNAME

Now, we can compile our website with one easy command:

make

And to publish it, simply commit and push (don’t forget to pull first!):

git add -A
git commit -m "my first post"
git push

And there you are, your first post is now available on our website!

You did it! You have now walked through the entire process of creating a blog, from buying your domain name and setting up hosting, all the way to writing and publishing your very first post. Congrats!