Creating a Website using Academic Theme for Hugo

In this post, we outline a step-by-step approach to making your own website using the Academic theme for Hugo. It is a fairly common practice to use this theme because it is aesthetically appealing, easy to use and flexible. Although wowchemy gives a detailed documentation, it does not provide an option to host the website on GitHub with the domain .github.io. This post serves as a quick guide for people with some experience with Git (but no experience with HTML/CSS) to set up their website. We first provide the essential steps for the setup and then explore how we can edit some aspects of the website.

Note: You should have a GitHub account, with Git installed in your computer (these directions have been tested on Ubuntu 18.04).

Create a GitHub page

The first step is to create a repository username.github.io, following the steps are outlined in their official guide.

Install Hugo

It is important to install Hugo because it is the framework responsible for building the website using the Academic theme.

Following the instructions provided by wowchemy, download a release of Hugo Extended, i.e. hugo_extended_<V>_Linux-64bit.deb (<V> denotes the version) and double-click the file to install with Ubuntu Software Center. Next, install Go, which is a dependency of Hugo:

sudo snap install --classic go

We used version v0.80.0 for Hugo. Installing an older version may lead to an issue similar to this.

Fork the starter-academic repository

Visit the starter-academic repository and click on Fork. Once a repository of the same name is created in your GitHub account, clone it to initialize the theme on your computer by using the following commands:

git clone https://github.com/username/starter-academic.git
cd starter-academic
git submodule update --init --recursive

Deploy your website on your GitHub page

As explained here, we need to add the username.github.io repo as a submodule in the public folder of the starter-academic repo. To do so, stop Hugo if it is running and delete the public folder if it exists (type rm -rf public). Then, type the following command:

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

Note that in case you want to clone these repos to make changes in your website from another computer, you must follow all the aformentioned steps starting from git clone ....

Commit and push your changes for the starter-academic repo and then for the username.github.io submodule, using the following commands:

git add .
git commit -m "Initial commit"
git push -u origin master

hugo

cd public
git add .
git commit -m "Build website"
git push origin master
cd ..

Visit the URL https://username.github.io to see your website!

Update content

The main content lies in section-wise folders in the content directory. The first step is to edit your bio and profile picture (avatar.jpg) in the content/authors/admin subdirectory. Next, in order to activate a widget and/or add the content, edit the markdown files in the content/home subdirectory (follow the instructions mentioned in each of the files), and then proceed to add the content in the same file (e.g. accomplishments.md) or in separate files in the respective subdirectories (e.g. content/projects) following the template provided in the _index.md file. You can visit this page to learn more about how to use different widgets.

Preview changes

In order to see how your website looks, you can type:

hugo server

This will provide you a link, such as http://localhost:1313/username.github.io/. Open your browser to visit this link and preview the changes. Make sure to stop Hugo before making additional changes based on the preview. If you are happy with the preview, you can commit the changes, following the steps mentioned above.

Customize your website

In this section, we discuss some specific aspects of customization, which might be helpful for beginners.

External URLs

In order to make sure that both internal and external URLs work fine, make/add the following changes in the config.toml file.

baseurl = "https:/username.github.io/"
canonifyURLs="true"

After this, the external URLs can be added as it is (starting from http or https) while the internal URLs would start with a / (e.g. /#about in the menus.toml file).

In order to make sure that the internal links open in the same tab, add hrefTargetBlank="true" in the config.toml file.

Changing the theme

Visit this page to learn about the available themes and fonts. You can also create your own theme by following the instructions listed on this page. You can follow this guide to learn about what the result of changing various variables would look like.