Creating a GitHub page using Hugo

Hello!

This is my first post here, so welcome. :)

Today I’m here to share the process of publishing your own personal GitHub page and managing the content using Hugo, the way I did it.

1. First things first, you’ll need a GitHub account.

2. Now that you already have one, you’ll need to create a repository named your-username.github.io. Choose a license, create a readme file, like any other project.

3. Open a shell prompt, go to the directory you want to clone your website project and do it.

$ cd path/to/my-repositories
$ git clone git@github.com:your-username/your-username.github.io.git

4. Go to the repository page on GitHub (something like https://github.com/your-username/your-username.github.io) and follow for Settings, then Pages. Under Branches, select master, change the folder to /docs and click Save. Now, every file you have on your-username.github.io/docs/ will get published. It’ll be the root of your website.

5. You already have a working webpage, now let’s take care of Hugo. You’ll have to choose here the best way of installing it, according to your operational system. Mine is MX Linux, which uses Debian packages, so I installed using the following command:

$ sudo apt install hugo

To check if the installation worked:

$ hugo version

The output must be something like:

$ hugo version
hugo v0.113.0-085c1b3d614e23d218ebf9daad909deaa2390c9a linux/amd64 BuildDate=2023-06-05T15:04:51Z VendorInfo=gohugoio

6. Everything okay to the next step. You’ll create your local website on the repository you cloned earlier and create some test content pages.

$ cd path/to/my-repositories/your-username.github.io
$ hugo new site . --force
$ hugo new content/test-page/index.md
$ hugo new content/posts/test-post/index.md

7. Write something at the end of the .md files you just created. Change the settings too, as you wish. Now let’s run a local server.

$ hugo server -D

Open localhost:1313 on your browser and ta-da! You have your running local server. The -D on the last command is for locally showing the pages marked as draft: true. These pages will not be available when you generate your HTML content.

8. Before pushing the changes, you’ll have to locate the config.toml or hugo.toml file. On this file you can set all the parameters of your website. For the GitHub page to work, at first, you’ll have to at least set:

baseURL = "https://your-username.github.io/"
publishDir = "docs"

9. So it’s time. Write a new post, like I teached you. Set the file to draft: false and save. Everytime you run the command hugo on your site directory, the HTML content will be generated under /docs based on the content you previously created and didn’t set as draft.

$ hugo
$ git add .
$ git commit -m "write your commit here"
$ git push

Wait a little. Soon your GitHub page we’ll be live, under https://your-username.github.io. And that’s it!

Create a portfolio, a blog, whatever you want. Have fun.

You can check Hugo documentation for more ways of setting and customizing your page.