Overview

GitHub came up with GitHub pages service, which hosts static web content free of cost. For Tech bloggers and for those who are trying to make their hands dirty in static web content creation, this is the best service at this moment. Read tagline of GitHub Pages -

alt text

GoHugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, GoHugo makes building websites fun again. It is theme based framework. You write markdown files and hugo creates static html by blending the content written in markdown files with the theme you selected. I am using hello-friend-ng theme for this website. And this entire post is written in single markdown file. Result is in-front of you. In future, I can choose any other theme and same content then will be presented differently on UI.

alt text

Now, In this post I will explain the step by step procedure to create a personal blog site using Hugo and then hosting this on GitHubPages.

Step 1 - Repository setup in GitHub

1.1 - To create a User Page site on GitHub Pages, create a repository using the naming scheme <username>.github.io.

My GitHub username is prashantbhardwaj hence I created a repository with the name as prashantbhardwaj.github.io. Now, when I will push any static web contents like HTML, CSS or JS files, those files will be hosted on GitHub Pages and can be accessed on this URL. Please Note - Content from the master branch will be used to publish your GitHub Pages site.

1.2 - Now create one more repository to keep the code of your Hugo Website project.

GoHugo will be used to create static content of your website. To do so, you need a github repository to keep you Hugo project code. Finally that generated static content will be pushed into <username>.github.io repository. You can give any name for your GoHugo project repository. I chose website.

Please note

These two repository will remain blank until step 3. Later we will use these repositories to push static website content and the GoHugo code which will be used to generate these static web content.

Step 2 - GoHugo installation

To install GoHugo in your local machine, follow steps mentioned on this page.

Step 3 - Learn GoHugo

Check this YouTube playlist, to learn GoHugo, step by step. During this learning exercise you will also create your GoHugo website project.

Step 4 - Link your GoHugo project to your github repository.

I hope during learning GoHugo by watching the youtube clips mentioned in previous step, you created your project. Now, it is time to link your GoHugo project with your website project repository you created under step 1.2. Steps to link your project code with GitHub repository are mentioned on your GitHub repository home page. Open that home page on your GitHub repository website and follow them.

Step 5 - Link your theme subproject with its github repository.

I hope during learning GoHugo by watching the youtube clips mentioned in previous step, you created your project and if so then probably you downloaded your chosen theme from it’s GitHub repository. For my project, I cloned hello-friend-ng theme from it’s github repository in my project’s themes directory. As mentioned on hello-friend-ng website, I used following command to link this theme subproject with my main website project -

$ git submodule add https://github.com/rhazdon/hugo-theme-hello-friend-ng.git themes/hello-friend-ng

There is a benefit of linking your theme subproject with your theme’s GitHub repository - whenever there will be any changes in your theme’s code, you can very easily download them by using git clone command.

Step 6 - Generate static content of your website

hugo -t theme-name command generates static content of your website in /public directory. If you will link this directory with the repository created under step 1.1 the by just pushing that generated static web content, your website will be hosted on GitHubPages. Steps to link your /public with GitHub repository are mentioned on your GitHub repository home page. Open that home page on your GitHub repository website and follow them.

Now add this github project as submodule with your main website project. Detailed steps are mentioned here.