# A guide to building and customizing a website using Hugo Academic theme

## 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](https://themes.gohugo.io//theme/academic/post/writing-technical-content/), [here](https://themes.gohugo.io//theme/academic/project/internal-project/), or [here](https://themes.gohugo.io//theme/academic/publication/journal-article/). The code that generates these pages can be found in the [GitHub repo for Academic](https://github.com/gcushen/hugo-academic), specifically the `layouts` [folder](https://github.com/gcushen/hugo-academic/tree/master/layouts). The actual HTML file, named `single.html` for each [content section](https://gohugo.io/content-management/sections/) 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 https://gohugo.io/templates/[Hugo templates](https://gohugo.io/templates/).

## Git submodules
Before we continue to the other types of pages, we will briefly explain [git submodules](https://git-scm.com/book/en/v2/Git-Tools-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](https://github.com/gcushen/hugo-academic) that was mentioned earlier. If you’re looking at this on [github.com](https://github.com/sourcethemes/academic-kickstart/tree/master/themes), 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](https://stackoverflow.com/questions/14404704/how-do-i-replace-a-git-submodule-with-another-repo/24782745)). 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(https://stackoverflow.com/questions/5828324/update-git-submodule-to-latest-commit-on-origin)).

## 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](https://themes.gohugo.io//theme/academic/post/). To build this page we use a [list page](https://gohugo.io/templates/lists/) 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](https://gohugo.io/templates/lists/#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](https://github.com/gcushen/hugo-academic/tree/master/layouts/section), 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](https://github.com/gcushen/hugo-academic/blob/master/layouts/_default/list.html), which does not produce a [pretty result](https://themes.gohugo.io//theme/academic/project/). 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](https://gohugo.io/templates/partials/) make up the building blocks for the section pages, as well as other pages such as the [widget page](https://sourcethemes.com/academic/docs/managing-content/#create-a-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_shwocase`. *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](https://gohugo.io/templates/lookup-order/) 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](https://github.com/eliaszwang/hugo-academic).

**Ref: https://eliaszwang.com/blog/hugo-academic-page-layouts/**

---

## “See all” button
If you started adding more than five (the default `count` param that’s set in front matter for the pages widget used on the homepage) posts or publications, you’ll notice a “See all posts” or “See all publications” button (really just a link) that appears in these sections on the homepage. These links allow the user of your website to navigate to the appropriate section pages (e.g. `domain.com/post`) directly from the homepage - a useful feature! By default, this button will only show up when the total number of items you have in that section is greater than the `count` that’s set in the front matter, which determines how many items are shown. Since I prefer to have the section pages always accessible, I modified the code in the [pages widget partials template](https://github.com/gcushen/hugo-academic/blob/master/layouts/partials/widgets/pages.html). At the end of the `pages.html` file you’ll see,

{{ if gt $count $items_count }}
<div class="see-all">
  <a href="{{ $archive_page.RelPermalink }}">
    {{ i18n $i18n | default "See all" }}
    <i class="fas fa-angle-right"></i>
  </a>
</div>
{{ end }}

Notice the line `{{ if gt $count $items_count }}`? That’s what we’ll want to remove, along with the corresponding `{{ end }}`, in order to show the “See all” link. So what you’re left with should look like,

<div class="see-all">
  <a href="{{ $archive_page.RelPermalink }}">
    {{ i18n $i18n | default "See all" }}
    <i class="fas fa-angle-right"></i>
  </a>
</div>

If you want to also add this feature to the portfolio widget that’s used for the projects section, there’s more work to do. In the same `layouts/partials/widgets` folder you’ll want to open up `portfolio.html`. At the top of the file, right after the `{{/* Initialise */}}` section you’ll want to add,

{{/* Localisation */}}
{{ $i18n := "" }}
{{ if eq $items_type "project" }}
  {{ $i18n = "more_projects" }}
{{ else }}
  {{ $i18n = "more_pages" }}
{{ end }}

{{/* Query */}}
{{ $archive_page := site.GetPage "Section" $items_type }}

which define some variables we will be using. Next, at the bottom of the file, right after the `<div>` section that uses the partials, you’ll want to add,

<div class="see-all">
  <a href="{{ $archive_page.RelPermalink }}">
    {{ i18n $i18n | default "See all" }}
    <i class="fas fa-angle-right"></i>
  </a>
</div>

This should look familiar, since it’s the same code as the one you saw just before in `pages.html`. The `$archive_page.RelPermalink` is the URL to the section page, so in this case `domain.com/publication` and the `$i18n` variable allows you to customize the text used for the link. It does this with the `i18n` function that I’ll explain in the next section.

## i18n
For a bit of background on internationalization and localization, aka i18n, you can check out the [Wikipedia page](https://en.wikipedia.org/wiki/Internationalization_and_localization) on it, but it’s basically just a simple translation module In any case, it’s not necessary since I’ll tell you exactly what you’ll need to do. First navigate to the [directory named `i18n`](https://github.com/gcushen/hugo-academic/tree/master/i18n) in the theme repo and open the `en.yaml` file, which provide the translation for English phrases. You’ll see a section for “Pages widget” that looks something like,

# Pages widget

- id: more_pages
  translation: See all

- id: more_posts
  translation: See all posts

- id: more_talks
  translation: See all talks

- id: more_publications
  translation: See all publications

we just need to add an additional entry like so,

- id: more_projects
translation: See all projects

to process the new `more_projects` argument. It actually doens’t matter where in the file you add these lines, but you should probably do it in the same section just for organazational reasons. If you run accross `i18n` again in the templates, remember this file, as it’ll likely be the answer to your problem.

## Format post dates
For those of you that plan on having a few posts on your site, you may have noticed that the “last updated on” dates for your posts are wrong - everything shows up as being modified on the current date. Don’t worry, this is a known problem, as you can see from [this GitHub issue](https://github.com/gcushen/hugo-academic/issues/1346). It turns out this is actually a bug on the side of Netlify, how your website is being hosted, rather than the Academic theme. However, this fix is super simple, you just need to change `HUGO_ENABLEGITINFO = "true"` to `HUGO_ENABLEGITINFO = "false"` in the `netlify.toml` file in the root directory of your website repo. After this modification, the dates should now correctly reflect what the `date` and `lastmod` params that are set in the front matter for each post.

I also ended up doing an additional modification to how the dates appeared after this fix in order to show *both* the original publish date as well as the last updated date. However, this is mainly a matter of personal preference so please feel free to skip the rest of this section if you’re not interested in making this change. The code that’s used to create the published/modified dates can be found in `layouts/partials/page_metadata.html` within the theme repo. I’ve extracted the relevant part for you here,

<span class="article-date">
    {{ $date := $page.Lastmod.Format site.Params.date_format }}
    {{ if eq $page.Type "publication" }}
      {{ $date = $page.Date.Format (site.Params.publications.date_format | default "January, 2006") }}
    {{ else }}
      {{ if ne $page.Params.Lastmod $page.Params.Date }}
          {{ i18n "last_updated" }}
      {{ end }}
    {{ end }}
    {{ $date }}
</span>

If you study the code you’ll see that `$date` is what will ultimately be shown on the page and it is set to the `lastmod` date (`$page.Lastmod`). Additionally, with the code

{{ if ne $page.Params.Lastmod $page.Params.Date }}
  {{ i18n "last_updated" }}
{{ end }}

it will add the “Last updated on” text in front of the date if the last modified date is not equal to the publish date. Since, I planned to also show the original publish date and didn’t want it to get too long I decided to edit the `i18n/en.yaml` file to change the translation of “last_updated” from “Last updated on” to just “Last updated”.

- id: last_updated
  translation: Last updated

To get both dates shown, you’ll want to add a couple lines to the code between the `<span>` tags. If you just want the solution, the end result should look something like this:

<span class="article-date">
    {{ $lastmod := $page.Lastmod.Format site.Params.date_format }}
    {{ $date := $page.Date.Format site.Params.date_format }}
    {{ if eq $page.Type "publication" }}
      {{ $date = $page.Date.Format (site.Params.publications.date_format | default "January, 2006") }}
    {{ else }}
      {{ if ne $page.Params.Lastmod $page.Params.Date }}
          {{ i18n "last_updated" }}
          {{ $lastmod }} |
      {{ end }}
    {{ end }}
    Published {{ $date }}
</span>

And that’s it, you’re done.

## Author list tips
### Highlight superuser
If you want to bold your name when it appears in the author list (e.g. for publications) there’s an simple setting in `config/_default/params.toml` to do this: `highlight_superuser = true`. However, there a few caveats about this method. In order for this to work, you’ll need to use the authors username that’s set in the user profile for the superuser. By default this will be admin, which you can see in `content/authors/admin/_index.md`. When you do this, the name that appears in the author list will be what is set in the title field of the same file. Since this display name is used on things like the homepage about widget, it is probably set to your full name. However, if you want to use something different (like first initial last name, which is common for pubications) it is not straightforward with this approach.

Therefore, I’ll show you another way to format the author names that offers more flexibility. In `layouts/partials/page_metadata_authors.html` you’ll need to replace ``{{ $name }}`` with ``{{ $name | markdownify }}``, which format the names using Markdown syntax. At the time of writing, there are two locations where this occurs. After this you can use "**YOURNAME**" in the authors front matter variable to make it bolded. Note: make sure you include the quotes. This makes it super easy to format any author name however you want.

### Author notes
If you want to add asteriks to indicate “equal contribution” or whatever else you can make use of the `author_notes` in the front matter. By setting these author notes it’ll add a symbol after the author’s name. The notes correspond exactly to the `authors` list, i.e. the first note for the first author, second for the second author, etc. To change the symbol that’s used, change the line ``<span title="{{.}}" class="author-notes">(?)</span>`` in `layouts/partials/page_metadata_authors.html`, replacing (?) with what you want (I use *).

---
**[Working with submodules](https://github.blog/2016-02-01-working-with-submodules/)**

**[How to undo (almost) anything with Git](https://github.blog/2015-06-08-how-to-undo-almost-anything-with-git/)**