Old website tutorial

Like apparently everything digital these days, not even a year later and most of the material I’ve written here is too out of date to be used as a direct tutorial (like nailing a flying carpet down, the reproducibility crisis might really be a thing). The academic theme has now moved to a quasi-GUI driven deployment system which both makes the site easier to create and deploy, but also strips it of the flexibility to modify it as I’ve outlined here. I am far too wed to this older format, and you could theoretically go back into github archives and download the older version that I use here. I’ll keep this page up as some of these tips are still relevant, but as always make sure you defer to the official documentation when learning how to do this.

There are a lot of links in here, to highlight some key resources I used while I was learning how to do this.

https://gohugo.io/

https://github.com/sourcethemes/academic-www

https://github.com/gcushen/hugo-academic

There are also several other tutorial linked at the end of this page that may be of use.

The creation of this website was spurred by a desire to streamline my digital footprint and more easily facilitate sharing (Google Drive simply doesn’t cut it here, and OneDrive is a whole different beast). However, building a website of your own is not as straightforward or accessible as it otherwise could be. Somehow among the vast sea of ways to design and host a website, I found workable solution in the form of the HUGO.

HUGO, a variation of the GO programming language, is touted as “The world’s fastest framework for building websites”. The HUGO documentation, particularly the hosting on github page, is a great place to start and is the “correct” way to go about creating a site. Below I will walk through how I managed to get it to work, your mileage may vary. I also recommend following the Academic theme instructions.

A cautionary note:
Your site doesn’t have to look like mine, feel free to pick any off the themes page. The theme you choose will do most of the heavy lifting, and hopefully you find one that does everything you want it to. If not, be prepared to spend a few days figuring out how HUGO and the themes work; there is no shortcut to creating new site behavior and I found it to be a bit unforgiving at times. In short, unless you REALLY want to sink time into this skillset, pick a theme and be happy with it 😊

“Step by step” instructions

Create a github account:

Create a Github account. I suppose in an ideal world your website name would be the same as your github username, but these can mismatch. I believe a free user account is restricted to one web page per account, and I haven’t bothered to test that limit.

(if on windows) Install git for windows:

Follow download and installation instructions at https://gitforwindows.org/.

Create the website url repository:

It is possible to buy a domain to customize your url, but in my case I’m cheap, and jimcoll.github.io is perfectly fine with me. Note that here I deviate from the HUGO docs. I don’t use github the right way, and I don’t really have a reason to use a separate github repository to keep the site files, instead opting to keep them on my local hard drive.

Create a website folder:

Next we need to create a folder where our website will live. This folder ideally shouldn’t be moved after you’ve created it, so place it somewhere useful (read: not the desktop). I gave into our digital overlords and moved most of my footprint to the cloud (OneDrive), so on my root folder I created a folder called myWebsite. Then right click on the folder and select the “Always keep it on this device”.

Installing HUGO:

Next you need to install HUGO in the website directory. Download the appropriate windows install from the HUGO releases. Unzip the file and place the hugo.exe file in your myWebsite folder.

Create the website:

This is where you need to start thinking for yourself. This process varies depending on which theme you end up choosing. Here I’ll just point you to the Academic doc pages. The raw doc files are also useful for formatting guidance.

Updating your website:

When you want to “manage your content”, it’s easiest to test it locally first. Shift-right click in the myWebsite folder and “Open PowerShell window here”. Then, type .\hugo server --disableFastRender. You can then open a browser and go to http://localhost:1313/. At this point, when you make and save changes to your files, HUGO will rebuild your site automagically and changes appear instantly on the browser. When you are happy with the edits you’ve made, you next need to generate your site. Again, from the myWebsite folder, open up PowerShell and generate the files with the .\hugo command. This repopulates the myWebsite\public folder. The last step is to push your new changes up to the repository, which you can do by right clicking on the public folder and selecting “Git GUI Here”, then…

Stage Changed files
create a commit message
Commit the changes, and
Push the changes up to the repository.

How this site was created:

This site is a smashup of the aafu and Academic themes. Although the Academic theme has just about every feature you might need, I fell in love with the AAFU theme and the accordion effect and was too enthralled not to try and integrate. To do this, you need to understand a little about how HUGO creates a website. HUGO uses a tiered folder system to generate the site, and will look in folders following a defined lookup order. Therefore, we need to overwrite the academic home page theme with the aafu theme. To do this, I first install the Academic theme, and then replace the partials folder with the aafu theme. The last step is to reconfigure the config_default/ folder with the aafu theme markdown files. Most of these are straightforward, but within the config_default\config.toml, we need to set the theme order as follows.

# Configuration of Academic
# Documentation: https://sourcethemes.com/academic/
#
# This file is formatted using TOML syntax - learn more at https://learnxinyminutes.com/docs/toml/
# Each configuration section is defined by a name in square brackets (e.g. `[outputs]`).

# Title of your site
title = "Jim Coll"

# The URL of your site.
# End your URL with a `/` trailing slash, e.g. `https://example.com/`.
baseurl = "https://jimcoll.github.io/"

# Enter a copyright notice to display in the site footer.
# To display a copyright symbol, type `&copy;`. For current year, type `{year}`.
copyright = ""

# Enable analytics by entering your Google Analytics tracking ID
googleAnalytics = ""

############################
## Advanced options below ##
############################

# Name of Academic theme folder in `themes/`.
theme = ["academic", "aafu"]

defaultContentLanguageInSubdir = false
removePathAccents = true  # Workaround for https://github.com/gohugoio/hugo/issues/5687
# Get user avatars from Gravatar.com? (true/false)
gravatar = false

# Align the main menu to the right of the page? (true/false)
menu_align_right = false

# Show estimated reading time for posts? (true/false)
reading_time = true

# Display next/previous section pager? (true/false)
section_pager = false
docs_section_pager = true  # Display pager in Docs layout (e.g. tutorials)?

# Enable in-built social sharing buttons? (true/false)
sharing = true
paginate = 10  # Number of items per page in paginated lists.
# Taxonomies.
[taxonomies]
  tag = "tags"
  category = "categories"
  publication_type = "publication_types"
  author = "authors"

[params]
    title = "Jim Coll"
    author = "Darshan Baral"
    description = "Jim Coll"
    copyright = ""

The rest of that file is the remains of the aafu theme.

Adding classes

To get menus to work, my /config/_default/menus.toml file looks like:

# Navigation Links
#   To link a homepage widget, specify the URL as a hash `#` followed by the filename of the
#     desired widget in your `content/home/` folder.
#   The weight parameter defines the order that the links will appear in.
[[main]]
  name = "Main Website"
  url = ""
  weight = 1
[[main]]
  name = "GEOG 358"
  url = "/courses/geog358/"
  weight = 2
[[main]]
  name = "GEOG 558"
  url = "/courses/geog558/"
  weight = 3
[[main]]
  name = "Drone Mapping"
  url = "/courses/dronemapping/"
  weight = 4
[[main]]
  name = "Random"
  url = "/courses/random/"
  weight = 4
  
[[geog358]]
  url = "/courses/geog358"
[[geog558]]
  url = "/courses/geog558"
[[random]]
  url = "/courses/random"
[[dronemapping]]
  url = "/courses/dronemapping"

Note that you will also have to set up these links in the AAFU theme as well, these menues are for the academic theme.

Make it your own

One of the best ways I’ve found to help improve my understanding of the software/deployment was to change some of the layouts. To add your resume to your image card as a link, and not as an icon as I have, you need to tweak the footer of the aafu theme, which should be in the themes\academic\layouts\partials\footer.html. Mine now looks like so:

<footer class="mb-4">
  <a href="https://jimcoll.github.io/courses/random/media/JamesCollSharedWebResume.docx">Download a "more traditional" resume
  </a>
  </br>
  powered by <a href="https://gohugo.io/">hugo</a> & deployed on <a href="https://github.com/">github</a>
  &middot;
  <i><a href="https://github.com/darshanbaral/aafu">aafu</a></i> by <a href="https://www.darshanbaral.com/">Darshan</a>
  & 
  <i><a href="https://github.com/gcushen/hugo-academic">Academic</a></i> by <a href="https://georgecushen.com/">George</a>
</footer>

Website width

The Academic theme follows the “best” practice of a mobile first design, and therefore scales pages to an otherwise anemic width. This is functional, but I was unhappy with it. Following tips on this post, you can change the head of the file at themes\academic\assets\sass\academic_docs.scss to a larger max width. A small bump is all you need to make it look prettier (960 is about 12 point font on a word document, 1440 is also a solid choice).

/*************************************************
 *  Documentation layout
 **************************************************/

.docs-article-container {
  max-width: 960px;
}

Adding tabbed content

Below is a code snipit that shows how to lay out material within a tabbed content box. Of note, in order to mix markdown into html elements, we need to append markdown=“1” to each div element, and DIV needs to be capitalized in order for this to render properly. I prefer removing indentations here, it makes writing the raw content easier and doesn’t break formatting on Chrome (other browsers untested). The   in the headers are added for spacing. Unfortunately, having headers above level 4 within tabbed boxes breaks the page generated table of contents on the right hand side and so should be avoided.

<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" href="#home">&nbsp;&nbsp;Home&nbsp;&nbsp;</a></li>
<li><a data-toggle="tab" href="#menu1">&nbsp;&nbsp;Menu 1&nbsp;&nbsp;</a></li>
<li><a data-toggle="tab" href="#menu2">&nbsp;&nbsp;Menu 2&nbsp;&nbsp;</a></li>
</ul>
<DIV class="tab-content" markdown="1">
<DIV id="home" class="tab-pane fade show active" markdown="1">
<h3>HOME tab is shown by default</h3>
<p>Some content.</p>
</DIV>
<DIV id="menu1" class="tab-pane fade" markdown="1">
#### This is content in markdown
Neat  

* List
* More list
</DIV>
<DIV id="menu2" class="tab-pane fade" markdown="1">
<h3>Menu 2</h3>
<p>Some more content in menu 2.</p>
</DIV>
</DIV>

How this renders in site:

HOME tab is shown by default

Some content.

#### This is content in markdown Neat

List
More list

Menu 2

Some more content in menu 2.

Extra Links

George Cushen, in addition to the academic docs, has likewise created a tutorial on his personal site detailing this workflow.
Leslie Myint’s website has a great post that effectively covers a large cross section of changes to the Academic theme.

Some links to style formatting, more for me than anything

https://github.com/gcushen/hugo-academic/issues/84