In this very first blog post, I will be covering how to deploy your static site generated by hugo on Gh-Pages at almost no cost.
Installing Go, Hugo and Git
The preliminary steps is to install all the necessary software required to build our static website.
Git We require Git for installing the preffered theme as a Git submodule and to have version control for our work. Eventually we’ll use Git and GitHub to deploy our website.
The easiest way to install both the software packages is through winget, the package manager for Windows system. Similar package managers are avaialable for both Linux (apt, yum, pacman) and MacOS (homebrew).
Run winget install Hugo.Hugo.Extended to install Hugo and run winget install --id Git.Git -e --source winget to install Git.
You can also choose to build Hugo from source and for that you require Go. While it is not necessary to install Go, it is recommended nevertheless.
Once Hugo is installed you can run hugo version to verify the installation. If the command returns with something like this, hugo v0.137.0-...+extended windows/amd64 BuildDate=2024-11-04T16:04:06Z VendorInfo=gohugoio, it implies that the installation was successful.
Choosing the theme, paperMod
We can now proceed to select our desired theme for the website. Many themes are avaialable at the Hugo themes section and you can choose one according to your needs. For me, the choice is paperMod. The theme’s documentation is well laid out and covers all the basics you need to know. You also get a working demo of the theme and get a good idea of how your own site would look like.
My preffered way to get the theme was adding it as a Git submodule. This required a couple of commands as explained in the theme’s documentation, viz.,
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
git submodule update --init --recursive
This method enables one liner update process, I can just run git submodule update --remote --merge in the root of the project to update the theme.
Populating some content
Now that we have all that is required to build the site we can start cooking. All the configuration for the site are listed in the hugo.yaml file. Each option is again explained in the documentation.
Adding some content is then easy and straight forward. All you have to do is run hugo new <your-folder-structure/filename.md>. This will create a markdown file in the folder structure you want to place the file into. A quick tip, create the folder with the name you want and place the file index.md in there. This creates a page bundle that means we can place assets in the same directory. You can add images to your page using markdown format, like . Once you have some content down in the file you can render your site by running hugo server and visit the site on localhost:1313.
Extending the head.html
You can tinker a lot with the hugo.yaml to get the configuration you want for your site and everything was working fine. Until, I pushed all the changes to Github and published the site on GitHub-Pages. All the stylesheets were broken and the assets were gone. For some reason the url was not being resolved properly for these properties. After a little digging online, I found out that I have to specify absURL in the stylesheet and all the favicon references in the .\themes\PaperMod\layouts\partials\head.html. We can do this by creating our own head.html at .\layouts\partial\. This will sort of extend the themes’ template and use the address provided in this file to link the stylesheets and the asset correctly.
The static directory
Another challenge that I have for now is that all the assets that I place in the .\static folder gets dumped into the root of the directory after building the site. Perhaps there is a fix. For now, this will do just fine.
Deploying on GitHub pages
With all these changes. I was again ready to deploy on Github-Pages and since I had done this in the past with another site. This step was a bit familiar to say the least.
Custom domain ($)
The only place where I had to invest was for securing a domain for myself and this step is entirely optional. For setting up the custom domain, firstly, you need to buy a domain of your choice and these days getting a domain is really resonable. You can choose any domain registrar for this purpose. I went with GoDaddy and bought the domain for 1500/- INR for 3 years. After three years, it will be 520/- INR per year. The price depends on the top level domain (TLD). For e.g., vaibhavnath.io was costlier than vaibhavnath.in.
Once you have access to your domain, you need to update the baseURl in your hugo.yaml config file and set it to your preffered subdomain. In my case it was baseURL: https://blog.vaibhavnath.in/. Do not forget the trailing slash, it is recommended to add that in the URL.
Next, go to your website’s repository on GitHub, navigate to Settings > Pages and under Custom domain, fill in the box with the custom domain you entered in the baseURL. Here, without the protocol and the trailing slash, i.e., blog.vaibhavnath.in
Mulitple GitHub-pages config
GitHub allows having many repository with GitHub pages. If you have more than one Github-pages, you need to use the base URL of the first page you had created and then use the sub-directory of second repository to acces its GitHub page.
For example, in my case the primary Repo had a Github page at https://vaibhavnath-jha.github.io and the name of your second repository is blog. Therefore, the Github page for the second repo would be reachable at https://vaibhavnath-jha.github.io/blog/. However, Github will redirect the request to the custom domain.
Domain Forwarding at GoDaddy
Once everything is configured we can setup Domain Forwarding from GoDaddy’s dashboard. This will allow our request to be served from the subdomain to the intended GitHub-page’s web address. If we do not do this, we cannot visit the site via blog.vaibhavnath.in
Setting this up is straightforward. From GoDaddy’s dashboard, you have to navigate to Domain > DNS > Forwarding and then fill up the form as you have configured your site. Below, there’s a screenshot of the form appropriate for my use-case. 
Enforcing HTTPS
After a crucial wait of 24 hours. You can enforce HTTPS on your static site. Github will run some DNS check to see if the DNS can be resolved successfully or not. Once done, your website will then have a valid certificate.
APEX domain and Name servers
I continue this topic in Part 2. Stay tuned. 😄