How to build your free academic portfolio website using Hugo and GitHub Pages

Learn how to create your personal website for free using Github Pages

7 min readJun 25, 2021

Having a personal website can be one of the most important assets if you want to showcase your skills to others. This is especially useful for freelancers seeking new projects and students hunting for jobs, but can be used by anyone to put forward their best side to the world.

I recently made a shiny new website for myself using Hugo and Github Pages. Although it took me quite some days to get the site up and running, I later realized that it is a straightforward process but there wasn’t any good resource with a streamlined instruction to build the site. And so, I’ve written this article so that you don’t go through the same struggle that I did. I hope this is the last article you’ve to visit before you get your site up.

Cutting to the chase, this article is divided into 7 subsections, which will get your site up and running in around 2 hours.

Prerequisites: You should have a GitHub account and know how to navigate through the site.

1. Installing Hugo

To install Hugo, go to Hugo’s releases page, scroll down to the Assets section and click on the download file as per your operating system.

Make sure that you download the ‘extended’ version only.

Unzip the binary into a new folder and set the folder’s address as a ‘Path Variable’.

Here’s an excellent video that explains the process in detail.

2. Setting Up Directories

The next step is to create a directory that will store the framework of your website. For the sake of this tutorial, I created the directory website in local disk (E:).

Next, open Windows PowerShell (or any terminal) and navigate to the website directory by using the following command:

> cd E:\website

Then use the following code to create a framework for your website called framework. (You can choose any name of your choice apart from framework ):

> hugo new site framework

If your code is executed successfully, you should see the following message on your screen:

You can also check to find that new files and directories have appeared in the framework directory.

3. Choosing the Website Theme

Hugo offers hundreds of themes on its themes page. You can choose from any one of them, according to your convenience and needs.

For the sake of this tutorial and for the intended readers, I’ll go with the Academic Theme, which is quite a popular theme and serves well for our purpose.

Once you’ve chosen your theme, click on the Download button to go to the theme’s GitHub repository.

Then click on the Code dropdown menu and copy the HTTPS URL.

Now, return to your PowerShell window. Type the following to change the working directory to the themes directory and clone the repository:

> cd framework\themes
> git clone https://github.com/wowchemy/starter-hugo-academic.git

4. Finishing the Site Framework

Now that you’ve downloaded the theme, it’s time to finish setting up the framework. The easiest and simplest way (noob way) is to do the following:

Go to exampleSite in the following path — framework/themes/starter-hugo-academic/exampleSite — and copy all the files and folder. Paste them in the framework directory, replacing any duplications.

Next, go to the starter-hugo-academic directory and copy everything in the directory except the exampleSite folder, LICENSE.md file, README.md file and theme.toml file. Paste them again in the framework directory, replacing any duplications.

Aannd that’s it! Now go back to the terminal and change the working directory to framework and enter the following:

> hugo server

This creates a local copy of how your website looks like currently. Copy the URL output (e.g. //localhost:1313/) and paste it into your browser to view your page.

5. Customization

You can now customize your site by editing the relevant files in a markdown editor. For the Academic theme, you can take help from the official documentation to navigate the files and folders.

Some files that you’d want to modify in the config/_default directory are:

config.yaml: contains the website name, copyright text
languages.yaml: language settings
menus.yaml: use this to edit the menus
params.yaml: contains the site theme, font size, contact info

For modifying the profile pic and the website pic:

Go to content/authors/admin/avatar.jpg, and replace the avatar.jpg file to change the profile picture
Change the icon.png file inassets/media/icon.png to change the website icon.

To modify/remove the various sections on the page, go to framework/content/home and edit the relevant files.

Edit these files to change the various sections on the page

6. Hosting Your Website on GitHub Pages

Now that you’re done with the framework and customization, you’re ready to deploy your site. You can use different platforms like Netlify to deploy your site, but for this tutorial, I have used GitHub Pages.

To begin, you need to create two new repositories in your GitHub account:

A repository with the same name as the framework folder.
A repository with the name username.github.io where username is your GitHub username.

Now copy the HTTPS link from the remote framework directory and open your PowerShell terminal.

Next, change to the local framework directory and type the following, replacing username with your GitHub username:

> git init
> git remote add origin https://github.com/username/framework.git
> git push -u origin master

Note:
While entering
> git remote add origin https://github.com/username/framework.git
if it shows
error: remote origin already exists.
type the following command to remove the origin, and then proceed as above.
> git remote rm origin

This will sync the local directory with the remote directory.

Now, copy the HTTPS key from the other repository with the name username.github.io. In your terminal, change to the initial website directory and enter the following commands:

> git clone https://github.com/username/yourgithubusername.github.io.git> cd framework
> hugo -d../username.github.io
> cd ../username.github.io
> git add .
> git commit -m "Initial Commit"
> git push -u origin master

And voila! Your website is now published. Visit your username.github.io repository and click on settings near the top right, scroll down to the Pages tab and you should see the following message:

Your site is published at https://username.github.io/

Click on the link to visit your site.

7. Updating Your Site

Now that your site is up and running, you may want to add new posts, or remove others, or just change the appearance. You can always do that by modifying the files in your local framework directory, and using the hugo server command to view the changes made.

After making the changes, you can push it to the remote repository and re-deploy your website. To do that, make sure that you’re in the framework directory and enter the following:

> git add .
> git commit -m "some changes"
> git push
> hugo -d ../username.github.io
> cd ../username.github.io
> git add .
> git commit -m "some changes"
> git push

And done! You can see the changes reflect on your site in around 10 minutes.

Leave a comment if you have any difficulty in setting up the site, I’ll try to help. And do leave claps if you found this article useful.