How to make a static web sites using Hugo-Github Page

Hello, In this article, I will cover creating simple static websites with hugo, a static website creation tool written in golang, hosting and publishing them on github. For this, I plan to prepare two different websites and use different third-party web services that will be useful to us while preparing them. First of all, I will talk about the use of hugo and then I will continue by creating a simple website.

Hugo

Hugo is a static web-site generator written in Go. This framework can quickly create a static website with terminal commands, thanks to a freely installed and available CLI tool. It also has different deployment options. In the hosting and deployment section of the gohugo.io site, it is explained how the website can be hosted on different web hosting platforms. But in this article, I will build a website that will be hosted on github and run in the domain username.github.io.

To download the framework and for a quick start, you can go to gohugo.io to install it on your system and start right away. If you are using a GNU distribution, the package is probably in your repository. On ubuntu and debian repositories hugo can be installed with;

$ sudo apt install hugo

On Fedora repositories hugo can be installed with;

$ sudo dnf install hugo

In hugo official website, it recommends installation with homebrew for both linux and mac. You can use the code below for Homebrew installation;

$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Then you can install hugo on your system with brew install hugo

After the installation, You can create a new web site with

$ hugo new site /path/to/your/site

on terminal.The file hierarchy is as follows. The config.toml file is the file that allows us to configure the website.

Now, this will open a blank page. Because there is no file in the layout.
You can clone one or more themes by selecting them from gohugo.io/themes and using git into the themes directory. using hugo new content/new_article.md it can be used to create a new content.

The website will start working on local server 1331 port with

$ hugo server 

If you want to take your experience further, you can create your own design by using the template tutorial on gohugo.io. But in this article, I will only create web pages using ready-made templates.

Creating a Static Portfolio Page

Portfolio pages are one of the best examples of static pages. These are the types of pages where the works done are exhibited and other accounts or communication e-mails are given as links. To create it, I first need to clone it with git by selecting from the portfolio themes listed on the themes.gohugo.io page. I choose the theme named hugo-shell-theme. One of the reasons why I prefer it is that it has a very simple structure. I will make my first attempt using this theme.
I'm clonnig the theme into themes directory with

$ git init 
$ git submodule add https://github.com/Yukuro/hugo-theme-shell.git themes/hugo-theme-shell
$ hugo server -t hugo-theme-shell -w -D

and starting the hugo server.It is currently running on the local server, but without any configuration. for this, I copy the content of the config.toml given on the github page of the theme and paste it into my config file in the directory. Below is the config file where I changed some parts and deleted the comment lines. I preferred powershell as shema.

It gives me an output like this:

For a better use, you can try to use a markdown file in the description. For example, you can find the portfolio website I use at noaahhh.github.io.

For Markdown usage, a description.md created in content is given to the description section of the config file.

description=/description.md

Then you can fill out whatever you want. If you go to the code side, you can see how it takes the parameters from the config file between the html tags.

Likewise, now I'm cloning the hugo-profile theme into the themes directory with git. This theme uses config.yml with .yaml extension as config file. I copy one of the 3 different yaml files (v1.yml) in the theme directory to my root directory as config.yml. And content of the website directory must be copied root directory. Our website is using the new theme on the local server after the command below.

$ hugo server -t hugo-profile -w -D --config=config.yaml

In this theme, you can also create your personal website by changing the parameters in the config file. In the following sections, I will talk about a more user-experience-oriented method.

e-commerce and product presentation pages

In this section I will try the Hero theme. Hero has a familiar type of company landing page and a clean interface. That's why I chose this theme. I'm creating a new website with Hugo. Then I clone this theme with git into the theme directory. There is a directory named example-site in the theme. This directory contains a pre-configured toml file and a ready-made website. I copy the contents of this directory to my home directory. Then I open my config file with an editor and delete the themesDir parameter. Then I can run hugo server and watch my website from localhost port 1313.

I've added an image below listing the terminal operations performed. You can check.

This way you can create websites to promote products or for a company portfolio.

Github Pages

There are multiple options for hosting a website built with Hugo. You can see the host and deployment options from the Hosting&Deployment link. We can host our website with services such as github, gitlab, netlify firebase. In the Github option, you can access the page we created via the username.github.io domain. In this application I will work on github.

We can publish our portfolio site, one of the websites we have prepared so far, on our own github domain. For this, we go to the directory where our portfolio website is located and create our website with the hugo command in this directory. A public file will be created in the directory and there will be our website using html to be published in this directory. If we submit it to our git repo within this directory we can publish our website using Pages there. We go to the Github page and open a repo named username.github.io.

We are connecting the public directory created according to the diagram above to our relevant git repo.

myHugoSite $ cd public
public/ $ git init 
public/ $ git remote add origin https://github.com/username/username.github.io.git
public/ $ git remote set-url origin http://<public-access-key>@github.com/username/username.github.io

After the last changes, to connect to our git repo, you should create a key by following the github->settings->developer Settings->Personal Access Key path and paste this key in the relevant section in the last command to link our repo.

public/ $ git add .
public/ $ git commit -m "initial commit"
public/ $ git push origin main

Then we can wait for it to be published from the setting-> Pages section in our repo. Our site will be published from the relevant url.

Different architecture for GitHub

If we want to publish our website over a subdomain with the same name as the repo, we can open a new repo and send the files in the public to this repo and publish it. If we examine the diagram below, we can create a website in our local system and keep this site on github. We can create a submodule link from another git repo in the "themes" directory. We can publish our files to be published with Github Pages by sending them to a new repo using the subdomain name to be published.

You can create a submodule with

mySite/ $ git submodule add http://github.com/Yukuro/hugo-theme-shell.git themes/hugo-theme-shell

mySite/ $ hugo -d ../myPortfolio

We can create html files in a directory called myPortfolio, which is in the same directory as our hugo website using like the command above.Then we can link this directory to the github repo and publish our website on a subdomain with the same name as the repo.

Hugo and Forestry.io

Forestry.io is a web service that makes it easy to manage the contents of our website on github using a graphical interface. This service is a CMS tool that works with frameworks such as hugo, jeykll. Content entry in personal blogs can be done easily. You can get more detailed information on the page.
It has a simple use. We just have to register for the service and then create a new registration with add site in the "My Sites" section and select Hugo as the "static site generator".

And then we connect our repo with the forestry.io service by choosing git provider.

Then we can prepare our posts in the blog in the document types we choose.

Apart from this, there are many CMS applications that work with Hugo. Cloudcannon, strapi.io, netlifyCMS can be given as examples. These are the systems we can use to organize our content between host and deployment.

The loop in the diagram represents the CMS service. With CMS services, operations such as content creation and editing can be done before deployment. By connecting with services such as AWS, Netlify, content editing can be done between the git provider and the deploymet service. And at the same time it provides synchronization with the website maintained in git.