I recently moved my personal/academic website from an expensive and complicated shared hosting plan to the simple GitHub Pages platform for free. At the same time, I also changed the engine from Jekyll to Hugo.
In this guide, I will discuss why you should also use Hugo and Github for your personal or academic website and cover how to install and use Hugo. This will enable you to configure a static site, create content (such as blog posts or academic publications), and publish your site for free with Github.
Like Jekyll, Hugo also requires a basic understanding of using the command line in the Terminal (Mac/Linux) or Command Prompt (Windows) app on your computer. If you are not interested in this, then I can highly recommend the following simpler alternatives:
- GitHub Automatic Page Generator - free and ideal for a very simple one page site. To get started:
- Signup for Github, preferably using a username based on your real name since your website URL will be in the form
- Login, click the “+” in the top right corner and create a new repository with the name
- From the main page of your new repository, click Settings and then Automatic Page Generator
- Follow the wizard to create your new website - help is available here
- Signup for Github, preferably using a username based on your real name since your website URL will be in the form
- SquareSpace - ideal if you need more features and customization. It is non-free (currently 12USD/month).
- WordPress - ideal for a highly customizable multi-page site. Although it has a free plan, I recommend paying the small fee (currently 2.99USD/month) for the Personal plan so that WordPress adverts are not shown on your site.
Whichever tools you decide to use to build your website, you can further personalize your website with your own domain name. I can highly recommend Namecheap for registering your domain, as it provides great value for money whilst providing fast support. To find a good and available domain, try a mix of your first and last names or initials, with either a
.me ending. Later in this article, we’ll look at how to integrate a new domain name with Github.
Why Hugo and Github?
While there are an enormous amount of website hosting and creation services available, a Hugo based website hosted on Github can have significant advantages over other options for a student or academic:
It’s free. Students will definitely appreciate this! Public repositories are free on Github. Hugo is free and open-source.
Simple editing. Instead of using HTML to write your content, you can write using popular Markdown and LaTeX math expressions.
Academic theme/framework. Manage your biography, publications, talks, news, teaching resources, projects, etc.
No dependencies. The beauty of Hugo is that it is just one standard binary program with no dependencies, so it’s dead simple to maintain a site made with Hugo. Jekyll and WordPress on the other hand have complex Ruby and PHP dependencies, respectively.
It’s multiplatform. Build your site from a Mac, Linux, or Windows computer.
Lightning fast to generate. Hugo builds my site, piecing together all the various parts and converting the Markdown content to HTML in less than a second. Jekyll took significantly longer and occasionally stopped working due to dependencies becoming deprecated or packages requiring to be manually updated.
Lightning fast to access. The inherent advantage of using a static site generator is that each page and asset can immediately be served to the client without any dynamic processing. Coupled with Github’s content distribution network, this means that wherever the client is in the world, they can instantly see your website.
Secure TLS (HTTPS). TLS helps guarantee that the content of your website has not been interfered with. Google recently began ranking secure HTTPS sites above insecure HTTP sites, and HTTP is being deprecated by major web browsers such as Chrome and Firefox. TLS is supported by Github and it’s the way forward.
It’s independent. Github is independent from your job, so it is portable. Whereas if your university affiliation changes, you’ll lose your university account and have to re-create a university hosted website with a new URL.
Solid roadmap. I have heard from a number of colleagues about universities dropping their own website hosting services and replacing them with other services or just not maintaining them adequately. Hugo and Github will not be disappearing any time soon.
Professional URLs. Github Pages URLs look professional (i.e. your-name.github.io) and there is also the possibility to use your own domain name with Github Pages if you wish.
Hugo vs Jekyll
In addition to the above, here are some specific reasons to use Hugo for your website if you are choosing between Hugo and Jekyll or considering migrating from Jekyll:
- Hugo can generate a site with 1000 pages in only 0.1 seconds, whereas Jekyll takes several minutes for the same site
- Hugo is a standard binary program, so it has no Ruby dependencies to maintain when testing/building the site locally on your computer
- Paginations, redirection, and live reload work right out of the box in Hugo without having to setup plugins
- In Hugo, you can just add
draft = truein the front matter of the post to save an unpublished draft, rather than having to move it to another folder
- Plus Hugo has numerous other benefits such as the content is organised in perhaps a more intuitive structure and has multilingual features built-in
Note that this is not an exhaustive list and the benefit-cost(time) ratio will depend on the size of any existing site and your skills and preferences.
I will assume that you have basic experience using the command line, as I will be demonstrating commands for the Linux/Mac Terminal.
Windows users may possibly need to adapt some commands for Windows command prompt. Note that Windows command prompt can be opened from Start menu > All apps > Windows System > Command Prompt.
For Windows users,
- Download the latest zipped Hugo executable (e.g.
hugo_<version>_Windows-32bit.zip) from the Hugo Releases page.
- Create a Hugo and bin folder:
- Move the downloaded ZIP file into your
- Extract the ZIP file such that
hugo.exeis extracted in
- Add Hugo to your Windows PATH:
- Click Start > System > Advanced System Settings > Environment Variables
- Double-click on PATH
- Click New, type
C:\Hugo\bin, and press
- Click OK to save and close the windows
For Mac users, assuming you have Homebrew installed, run the following in your Terminal app:
brew update && brew install hugo
For Ubuntu Linux users,
- In your Terminal app, type
arch. If the output is x86_64 then you’ll want to download the 64-bit file ending in -64bit.deb in the next step, otherwise download -32bit.deb.
Download the latest Hugo package for your system (as noted in the previous step) from the Hugo Releases page and install by double clicking it, or via command line. For example:
cd ~ wget https://github.com/spf13/hugo/releases/download/v0.17/hugo_0.17-64bit.deb sudo dpkg -i hugo*.deb
Note that further installation guides are available in the Hugo documentation.
Getting started with Hugo
When I first started using Hugo, there were no website themes or frameworks available for academic staff or students. Hence, I went about creating one, namely Hugo Academic - as seen in the image below. The key features are:
- Designed for academic staff, students, or general personal use
- Includes Biography, Publications, Projects, News/Blog, Teaching, and Contact widgets
- Write in Markdown for easy formatting and code highlighting, with LaTeX for mathematical expressions
- Academic linking (Scholar etc.), Google Analytics, and Disqus comments
- Responsive and mobile friendly
- Simple and refreshing one page design
- Easy to customize
The theme/framework rapidly gained the attention of academics and has now become very popular with thousands of users worldwide. Since the theme is highly customizable, letting you pick and choose which features you want, it’s possible to generate many different types of website, even including general personal or freelance websites.
To create your Hugo website with the Academic theme/framework:
Open your Terminal/Command Prompt app, navigate to your desired location using the
cdcommand, and create a new website:
cd ~ hugo new site my_website cd my_website
Install the Academic theme with git:
git clone https://github.com/gcushen/hugo-academic.git themes/academic
Or alternatively, download Academic and extract it into a
themes/academicfolder within your Hugo website.
Copy the contents of the
exampleSitefolder to your website root folder, overwriting existing files if necessary. The
exampleSitefolder contains an example config file and content to help you get started. The following command can be used to copy the folder via the command line:
cp -av themes/academic/exampleSite/* .
Start the Hugo server from your website root folder:
hugo server --watch
Now you can go to localhost:1313 and your new Academic themed website should appear. Note that you can press the
Cbuttons in the terminal when you wish to stop viewing your local website using the Hugo server and be able to type other commands again.
Add your own content (homepage widgets, news/blog posts, academic publications, projects etc.)
Build it by running the
hugocommand. This will generate a folder called
public/that contains all the HTML code and assets for your website.
Deploy it using Github, as discussed in the next section. Or alternatively, by copying the
public/directory (by FTP, Rsync, etc.) to your production web server (such as your university’s hosting service).
Getting started with Github
Go to Github and register for an account if you have not done so already. Github encourage using your real name for your account username, and this can help your Github URL (which you will be assigned later) to look professional.
Once you have created your Github account and visited your profile, we will create two new repositories (often abbreviated as repos) on Github with the following names:
websiteor any other name you like - we will save your Hugo content to this repo
USERNAMEis your Github username - we will save the generated HTML website to this repo
To create each repository, click the “+” icon in the top right corner and then choose “New Repository”. For the
USERNAME.github.io repository, ensure to check the Initialize this repository with a README box, as this will make the next step easier. Enter a brief description if you like and then “Create repository” for each one.
In your Hugo
config.toml file, set
baseurl = "https://USERNAME.github.io/", where
USERNAME is your Github username. Stop Hugo if it’s running and delete the
public directory (if it exists) with:
rm -r public/
Install git if it’s not already present on your system. You can check by running
Whilst your terminal is still in the root folder of your website, initialize a git repository and add the remote Github repository that you created:
git init git remote add origin https://github.com/YOUR-USERNAME/website.git
Add your USERNAME.github.io repository into a submodule in a folder named public:
git submodule add https://github.com/YOUR-USERNAME/YOUR-USERNAME.github.io.git public
Add everything to your local git repository and push it up to your remote repository on GitHub:
git add . git commit -m "Initial commit" git push -u origin master
Whilst running the above commands you may be prompted for your Github username and password. Next, regenerate your website’s HTML code by running Hugo and upload the public submodule to GitHub:
hugo cd public git add . git commit -m "Build website" git push -u origin master
Once Git has finished uploading your site to Github, you can open your new
https://USERNAME.github.io website in your browser, substituting USERNAME with your Github username.
A practical example
As discussed, Hugo Academic includes an example website for you to use as a template for your website. You can view the code for this online. My personal website is based on this example site.
You can use your own domain name with Github Pages if you wish. You will need to register a domain, point it to Github, and create a
CNAME file in the
static folder of your website, so that Github knows your intentions. For more information, check out the domains guide by Github.
Remember that after you have setup a custom domain, you will need to wait approximately 24-48 hours for the DNS to propagate and then you’ll need to update
baseurl in your Hugo
config.toml to your new URL, regenerate the site with the new urls, and redeploy.
If you are feeling more adventurous, you can consider automating deployment such that when a change is pushed to your Hugo
website repository, your
USERNAME.github.io repository is automatically re-built.
You can fork the code for the live demonstration website, which is based on the example code above. However, note that this demo repository is setup with project-based Github Pages as a branch named
gh-pages, rather than with user-based Github Pages as a separate repository to the Hugo content. You’ll want to use user-based Github Pages which requires creating two separate repositories, as previously described. Also, the Academic theme is setup as a git submodule so that theme updates can easily be applied. Wercker is utilized for continuous deployment. Hence, you’ll need to connect Wercker with your Github account and add a Wercker webhook to your
website repository on Github. If there is interest, I will consider expanding on this setup in a future post.
Hugo Academic is a great way to get a personal or academic website up and running quickly and easily. Static websites, such as Hugo Academic, load significantly faster than traditional content management system (CMS) sites whilst being much easier to manage and much harder to hack. Individuals do not usually need dynamic database-driven content or the advanced features that content management systems offer. With Hugo Academic, you can focus your energy on creating great content instead of administering a complex system.
Happy creating! Feel free to leave your comments or questions below!