Publishing a [github.io Blog] with Hugo and Github Pages

Koowoy
TIL

0. Prerequisites

1. Install Hugo [for Windows 10]

  1. Create a new folder with the name “Hugo” on C: directory.

  2. Inside C:\Hugo, create another new folder with the name “bin”.

  3. Download the latest version of Hugo for Windows (which is in .zip format) from Hugo Releases.

  4. Extract the zip file into the C:\Hugo\bin, which was created in Step 2.

  5. Now the hugo.exe file is executable from this folder. However, the goal is to be able to run hugo from anywhere on the desktop. Therefore, hugo needs to be added to the Path in the Environment Variables of the desktop. Search for “Environment Variables” in the start menu’s search. In the User variables section, double-click on Path from the list. Click “New” and add C:\Hugo\bin to the List. Click on all the okays.

  6. Now hugo is installed and executable from anywhere on the desktop. To check if hugo was installed correctly, turn on the command prompt or bash and type hugo version on the terminal.

2. Create 2 new repositories on the github account

On your Github account, create 2 new public repositories with the name ‘blog’ and ‘[your-account-name]/github.io’. The first repository is where all the source code for the hugo will be stored, whereas the second repository will be used to actually publish the site.

3. Start a new site with Hugo and add a theme

  1. On the terminal type in hugo new site blog in order to compile a new Site.

  2. Pick out a theme from the themes provided by hugo.

  3. In order to install the theme, follow the instructions of the demo page of the theme. There are 2 ways of applying the thems to hugo using git. The first is cloning the theme repository with the code $ git clone https://github.com/[theme-repo-address] in C:\Hugo\blog\themes. The second is to create a submodule at C:\Hugo\blog directory by typing git init and git submodule add https://github.com/[theme-repo-address] themes/[theme-name]. The second method makes sure that updates of the theme will be applied to the compiled site. However, the second method didn’t work for me for some reason, and this is maybe a problem to be solved in the future.

  4. To finish applying the theme, execute the code echo 'theme="[theme-name]"' >> config.toml on the terminal.

  5. Before checking to see the theme has been applied correctly, create a sample content. Type in hugo new posts/sample-post.md on the terminal in the blog directory. Open the markdown file on an editor, and make sure that draft is set to false, since a draft will not show on the page.

  6. To check if everything was done correctly, execute the code hugo server on the terminal in the blog directory. On the message on the terminal, the address for the page will be shown (ex. http://localhost:1313/).

4. Connect to Github repositories to pusblish on Github Pages

In order to use the ssh address for github, ssh keys must be added in the setting of github account. This is thoroughly explained in this github doc.

1. Blog Repository

This repository will be assigned as the remote repo for the local blog directory.

In the directory C:\Hugo\blog execute git init and git remote add origin [git@github.com:[your-user-name]/blog.git].

2. github.io Repository

This repository will be assigned as the submodule for the local blog directory.

Prior to this, in the github.io repository, at least 1 commit and a main branch has to exist in order to proceed in creating a submodule.

  1. On the desktop, clone the repository by executing git clone https://github.com/[your-user-name]/[your-username].github.io.git.

  2. Move into the created directory and execute the code git checkout -b main to create the main branch.

  3. Create a simple readme by typing in touch README.md.

  4. Stage, commit and push to the repository by executing the following codes:

    git add .

    git commit -m "adding readme"

    git push origin main

  5. Now add the submodule. In the directory C:\Hugo\blog execute git submodule add -b main [git@github.com:[your-user-name]/blog.git] public.

    By doing this, when hugo rebuilds the website, this will be compiled in the public directory, which we can push to the github.io repository.

5. Build the page using hugo and deploy on Github Pages

  1. In the blog directory and execute the code hugo -t [theme-name].

  2. Move into the public directory and push to the repository by executing the following codes again:

    git add .

    git commit -m "adding readme"

    git push origin main

  3. On the github webpage in the github.io repository, click on the settings tab. to the bottom on the GitHub Pages section, click on the published webpage url to check the blog online.

Finished!