How to Create a Website with Hugo Academic Theme: Basic Setup

While the Academic theme for Hugo provides a great set of Docs, I still needed to spend a lot of time figuring out how to do certain things. Therefore, this is the first of several posts describing how to set up and customize a website using Academic. The goal of this series is to provide a clear, detailed overview of the process so I’ll have a resource to refer back to if I encounter a similar problem in the future. Hopefully this information will be useful to you too. These posts will assume some basic familiarity with coding and common tools (e.g. git).

Create a site with GitHub and Netlify

If you followed the first part of the Installation guide, you will have created a GitHub repo named “academic-kickstart” that contains the code for your website and will be hosting the site with Netlify. For reference, the GitHub repo that you created is based off the one found here. I will be referring to this repo as the website repo. This part is pretty straightforward, the only thing that you might want to do that’s not mentioned in the guide is to change the name of the repo from “academic-kickstart” to something else (i.e. yourname-website). If you do this, make sure you also change the repo URL accordingly in the Build Settings on Netlify.

You are now ready to start personalizing your site. The first thing to do is to navigate to config/_default where you’ll find the sites configuration files. The main changes you’ll want to make to config.toml are the title and adding the copyright. If you plan to use Google Analytics (which I would recommend) then you will also want to set the tracking code here by adding googleAnalytics = "UA-XXXXXXXX-X", replacing UA-XXXXXXXX-X with your unique code. For params.toml there are a few more changes that you’ll have to do. First is to change math = false to math = true to enable $\LaTeX$ math (see here for more info about syntax). Next you’ll want to change the contact information for your email, phone, address, social media links, etc. If you want to disable the social media sharing buttons on the bottom of the page, you can do that here by setting sharing = false. The params.toml file also includes options to change the theme and font_size.

The docs then continues on to describe how to set up the Netlify CMS in the “Edit content online” section. If you wish to do this, after you set the registration to Invite Only, you’ll need to go to the “Identity” tab in the menu at the top in Netlify to invite yourself as a user. Note: this is not the same as the “Identity” tab in the “Settings”. It took me a while to figure that out - I don’t think it’s mentioned anywhere in the docs. If you’re okay with editing the files on your computer locally and pushing to GitHub, the CMS isn’t really necessary.

Building your homepage

At this point, you’re ready to begin making the website your own. You’ll want to roughly follow the Getting started and Build your homepage pages, but I’ll highlight the important parts here. You might have noticed that the Academic demo site actually contains some elements that are not present on the website you get by following the installation procedure described above. Therefore, it may be useful to look at the code that generated the demo site, which can be found here.

The icon, which is the small image that shows up on the left of browser tabs, can be added by saving an image named icon.png in the assets/images/ folder. If you have a logo, placing an image named logo.png into the same folder will put your logo at the left-hand side of the navigation bar. If you don’t have a logo, the title of the site (set in config.toml) will be used instead. You can update the information in your profile by editing content/authors/admin/_index.md. You can also add an avatar photo by saving an image named avatar in this folder. For customizing the look of your homepage, the Build your homepage page should pretty much everything you’ll need to know. If you want to remove that ugly “Quickly discover relevant content by filtering publications.” alert in the publications section just go to content/home/publications.md and remove the last three lines, starting with {{% alert note %}}.

Deploy locally

It is useful to be able to view the results of the changes you make before you deploy them to the live website. To do this you’ll need to first install Hugo. On macOS you can just run brew install hugo (check the installation with hugo version). After installing, just run hugo server in the root directory of your website repo. You can add the -D option (i.e. hugo server -D) to also see the posts with draft: true. While the server is running, it’ll automatically check to see if any of the files changed and update the local site, which you can find at http://localhost:1313. Review the Hugo basic usage docs for more details.