How to Create a Website with Hugo Academic Theme: Page Layouts

The next step after the basic customization of the homepage widgets settings and other small changes is designing the layouts of different pages on your website. In this post I will describe how to customize the templates provided in the Academic theme in order to achieve your desired look and function for your site.

Single pages

Single pages, as the name suggests, are the pages for single pieces of content. For example, a single blost post, a project description, or publication overview. The URL for these pages will be of the form domain.com/section/example-title, e.g. domain.com/post/my-first-post. Examples of actual single pages from the demo site can be found here, here, or here. The code that generates these pages can be found in the GitHub repo for Academic, specifically the layouts folder. The actual HTML file, named single.html for each content section can be found in the directory with the corresponding name, e.g. layouts/project/single.html. To understand how these HTML files work see the docs on Hugo templates.

Git submodules

Before we continue to the other types of pages, we will briefly explain git submodules and how they are used for this theme. Essentially, submodules allow you to make a git repo a subdirectory of another git repo. If you look at the themes directory in your website repo you should see a subdirectory named academic, which is actually a submodule based on the GitHub repo for Academic that was mentioned earlier. If you’re looking at this on github.com, you’ll see that the folder icon has a white arrow on it.

In order to make changes to this theme repo, you’ll want to create a fork, then update the submodule to use your theme repo. To do this, you first need to change the URL for the submodule from https://github.com/gcushen/hugo-academic.git to the URL for your theme repo that you just forked (e.g. https://github.com/your-github-handle/hugo-academic.git) in the .gitmodules file, which is located in the root directory of the website repo. Next, you’ll run the following git commands to actually update the submodule: git submodule sync and then git submodule update --init (relevant stackoverflow question). If you click the themes/academic directory on github.com it should now take you to your forked theme repo. The final thing regarding submodules is that if you change the theme repo, these changes are not automatically updated in your website repo. In order to propogate the changes to the website repo, you’ll need to run git submodule update --remote --merge, then the standard add, commit, push commands (relevant stackoverflow question).

Section pages

Section pages are the ones that will give an overview of all the content within that section, e.g. a list of blog posts or publications. The URL for these pages will be of the form domain.com/section. An example from the demo site for a posts page can be found here. To build this page we use a list page template that defines how the full section page can be composed out of smaller elements that contain just a summary for each single page. The order content section of the doc is useful to look at since it describes how you can change the order of the list elements as well as their default ordering (Weight > Date > LinkTitle > FilePath). We also have a template that generates and formats these summaries, but talk about that a bit later.

The HTML files for making the section pages can be found in the layouts/section directory of the theme repo. If you haven’t modified anything yet from the original repo, you should see four *.html files. If the section does not have a corresponding HTML file here the section page will be made using the default, which does not produce a pretty result. You might notice that project.html is missing in this folder, which mean you’ll need to create one yourself if you want a nice looking projects page. If you do, you might also need an index.md file in the content/project subdirectory of your website repo to any parameters you use in project.html template. It’s worth mentioning now, that the default templates are located in layouts/_default. If you look into the files for the section pages, e.g. layouts/section/post.html, you’ll see something like,

{{ range $paginator.Pages }}
  {{ if eq $.Params.view 1 }}
    {{ partial "li_list" . }}
  {{ else if eq $.Params.view 3 }}
    {{ partial "li_card" . }}
  {{ else }}
    {{ partial "li_compact" . }}
  {{ end }}
{{ end }}

these lines with partial determine how each list entry looks on the section page. The docs on might be useful.

Partials

As explained above, partials make up the building blocks for the section pages, as well as other pages such as the widget page that’s used for the’homepage. The code for them can be found in layouts/partials. The relevant files that are used for section pages are: li_list.html, li_compact.html, li_card.html, and li_citation.html. These options govern the amount and type of information that will be shown. For example, li_citation.html uses parameters like publication or publication_short which are only relevant for pubications.

Widgets

Inside the layouts/partials directory you will also see a widgets subdirectory which contains templates for determining how the widgets appear. If you take a closer look at these files, you’ll also find that they use partials, although some may use ones different to those listed above. For example, layouts/partials/widgets/portfolio.html uses partials specific for it, e.g. portfolio_li_compact or portfolio_li_shocase. Note: The post and publication sections use the pages widget and the project section uses the portfolio widget.

Check out Hugo’s lookup order docs for more information about how Hugo determines which template file to use. Additionally, if you want to take a look at the theme repo I use to generate this site, click here.