How To Build An Academic Website Using Hugo And Github Pages

Aug 3, 2022 8 min read

1. Introduction

Internet and social media are powerful tools to build your presence as an academic scholar, network with peers and promote your research. Besides social media, an essential online presence that one can have is a personal website.

This post describes how to set up a personal academic website using the static website generator Hugo and publish it using GitHub Pages. The post is targeted toward students, scientists and faculty members who have a basic knowledge about how to use Git, command line tools and Github.

Our final goal is to have two Github repositories: a source repository called username_website, which contains the website’s unprocessed resources and a host repository called username.github.io which hosts the website.

2. Create a Website

2.1 Prerequisites

As mentioned before, you need certain prerequisites to follow this post. The requirements are listed below.

  • You must have a Github account.
  • You must have Git installed.
  • You must have Go installed.
  • You must have basic Command line knowledge.

2.2 Install Hugo

Download and install the hugo from gohugoio/hugo into your computer.

Note: Install the latest extended-version of hugo.

2.3 Download A Theme

Open the terminal and from your home directory, type the following commands.

git clone https://github.com/wowchemy/starter-hugo-academic.git username_website
cd username_website
git submodule update --init --recursive
Note: You must replace 'username' with your GitHub username.

2.4 Launch The Website

Make sure you are in the username_website directory. From the terminal, type the following command

hugo server
Note: This will launch a server on your terminal which will locally host your website. Copy the URL displayed on the terminal and paste it into the browser of your choice. You must be able to see the website now.

3. Basic Customisation

3.1 Open Files In Text Editor

To customise the website, we need a text editor. You can choose any of your favourite text editors to do the task. In case you are using atom, you can open the files as follows:

Make sure you are in username_website directory. Now type

atom .

This must open all the files in the directory on the atom text editor window. Now, if you edit and save any file, the changes should reflect on your local browser window.

3.2 Personal Details Customisation

Following are the essential files you need to modify to customise your website:

  • config/_default/config.yaml : Edit this file to modify general website information.
  • config/_default/params.yaml : Edit this file to customise your website.
  • config/_default/menus.yaml: Edit this file to customise the menu bar.
  • content/authors/admin/_index.md: Edit your personal information here.

3.3 Profile Picture Customisation

The profile picture and the website icon can be modified as follows:

  • content/authors/admin/avatar.jpg
  • assets/media/icon.png

Replace avatar.jpg and icon.png with the pictures of your choice.

Note: Do not change the filenames. Just replace the files and retain the same filenames.

3.4 Widgets Customisation

To modify the widgets on your homepage, change the files in the content/home/ folder. In case you want to delete a section, open the related file and set active:false. More details about customisation can be found on wowchemy website.

4. Modify .gitignore File

In .gitignore file delete the line saying public/.

5. Delete public/ Folder

Completely delete public folder if it exists.

6. Create A New Repository username_website On GitHub

To create a new repo on GitHub, log in and go to the GitHub home page. You can find the “New repository” option under the “+” sign next to your profile picture in the top right corner of the navbar. After clicking the button, GitHub will ask you to name your repo and provide a brief description.

  • Name the repo username_website.
  • Provide a brief description, for example, “Contents of my academic website”.
  • Click on Create repository button.

7. Modify .git/config file

Currently .git/config file looks like shown below

[core]
	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true
	ignorecase = true
	precomposeunicode = true
[remote "origin"]
	url = https://github.com/sourcethemes/academic-kickstart.git
	fetch = +refs/heads/*:refs/remotes/origin/*
[branch "main"]
	remote = origin
	merge = refs/heads/main

Modify the url to look like this

[core]
	repositoryformatversion = 0
	filemode = true
	bare = false
	logallrefupdates = true
	ignorecase = true
	precomposeunicode = true
[remote "origin"]
	url = git@github.com:username/username_website.git
	fetch = +refs/heads/*:refs/remotes/origin/*
[branch "main"]
	remote = origin
	merge = refs/heads/main

8. Add Files To Staging Area And Create A Commit

After you have completed customising the website, add all the files to the staging area with the following command. Make sure you are in username_website directory.

git add .

Once all the modified files are added to the staging area, leave a short commit message which summarises your changes.

git commit -m "fully customised version of the website"

9. Point Your Directory username_website To Your Newly Created username_website Repo On Github

From username_website directory in the terminal type

git push -u origin --all

Now, login to your account in Github and make sure that all the contents of your website are uploaded to username_website repository. This repository will hold all the contents of your website on Github. Now that we have a secure copy of all the contents, we can move on to create a new repository to host your website.

10. Create A New Repository username.github.io On GitHub To Host Your Website

Create a new repo on GitHub named username.github.io. Log in and go to the GitHub home page. You can find the “New repository” option under the “+” sign next to your profile picture in the top right corner of the navbar. After clicking the button, GitHub will ask you to name your repo and provide a brief description.

  • Name the repo username.github.io. The ‘username’ here must be same as your Github username.
  • Provide a brief description, for example, “My academic website”.
  • Click on the Public option
  • Initialise the repository with a README file and a licence.
  • Now click on Create repository button.
Note: Please make sure that these steps are strictly followed without any changes.

11. Update The Website URL

Update the website url in config/_default/config.yaml file. The base url must look like

baseURL: 'https://username.github.io/' # Website URL

12. Clone username.github.io To public Directory

From the terminal, run the following commands:

cd username_website
git clone https://github.com/username/username.github.io.git public
Note: If you get: warning: You appear to have cloned an empty repository. – go back to the Github repo and create a README and licence file.

13. Make A Test File To See If The Website Works

Let us make a text file index.html to check if the website works as intended. From the username_website directory, type the following commands

cd public
touch index.html
echo '<h1>Hello World - v0</h1>' >> index.html

Now push this change to the Github repository corresponding to the website. That is the repository named username.github.io using the following command.

git add .
git commit -m "test webpage"
git push

If everything goes well, towards the end of the terminal output, you must be able to see the following lines.

To github.com:username/username.github.io.git
Note: If you see the above line in the terminal window, skip the next step and move on to step 15.

Else, you might encounter the following error

remote: Permission to username/username.github.io.git denied to username.
fatal: unable to access 'https://github.com/username/username.github.io.git/': The requested URL returned error: 403
Note: In case you encounter the above-mentioned error, go to the next step 14.

14. Clone The Repository username.github.io.git Outside The username_website Directory

Make sure you are outside username_website directory. Then type the following commands to clone username.github.io.git repository into your computer.

git clone git@github.com:username/username.github.io.git
cd username.github.io
echo '<h1>Hello World - v1</h1>' >> index.html
git add index.html
git commit -m "testing if the website works"
git push

After successfully completing the above procedure we move this repository into the username_website. Run the following commands from outside the username_website directory.

rm -rf username_website/public
mv username.github.io username_website/public

Now type the following commands,

cd username_website/public
echo '<h1>Hello World - v2</h1>' >> index.html
git commit -am "testing if the website works from within hugo project"
git push

Wait for a few minutes and go to the website https://username.github.io. You must be able to see the contents of the newly published index.html page.

15. Configure public As A Submodule

Add username.github.io.git as a submodule using the following commands. Make sure you are in username_website directory.

cd public
git submodule add -b master https://github.com/username/username.github.io.git public

Now open .gitmodules file and make sure the contents of the file look like shown below.


[submodule "public"]
	path = public
	url = https://github.com/username/username.github.io.git
	branch = master

16. Construct And Publish Your Website

Now construct your website using the following command. From username_website directory run the following command.

hugo

The above command will construct the html, css and js files necessary to show your website online in the public folder. Now run the following commands to push your website online

cd public
git add .
git commit -m "first version of the website is now online"
git push
Note: Step 16 must be followed every time you make changes to the website.

Go back to https://username.github.io and check out your newly published website!

Shreyas Punacha
Shreyas Punacha
Postdoctoral Researcher

My research fields are Physics and Computational Biology. My research interests include neuroscience, tongue and jaw kinematics, cardiac arrhythmias, low-voltage defibrillation, excitable media, pattern formation, blackhole thermodynamics and fluid gravity.