Hugo File Naming Convention

Hugo gives us two options to name standard page files: as TITLE/index.md or TITLE.md where TITLE is your page name.

The page name should be lowercase and using hyphens (-) instead of spaces.

Both approaches result in the same output, so you can choose your preferred approach to naming and organizing files. A benefit to the folder-based approach is that all your page’s files (such as images) are self-contained within the page’s folder, so it’s more portable if you wish to share the original Markdown page with someone.

The homepage is a special case as Hugo requires the homepage and listing pages to be named _index.md.

Docs Navigation

The docs navigation is automatically generated based on the content in the docs/ folder and is sorted alphabetically.

The order of pages can be changed by adding the weight parameter in the front matter of your Markdown files.

In the example below, the example.md page will appear before the test.md page as it has a lower weight:

Page example.md:

1
2
3
4

---
title: My Example
weight: 1
---

Page test.md:

1
2
3
4

---
title: My Test
weight: 2
---

Folder Structure

There are 4 main folders for Hugo-based sites:

  1. content/ for your Markdown-formatted content files (homepage, etc.)
  2. _index.md the homepage (Hugo requires that the homepage and archive pages have an underscore prefix)

The content folder contains all the content files for the website.

  • New items

It is convenient to use archetypes to generate new files easily. By default, the URL of the new paper would be baseURL/papers/new_paper/. But the URL can be customized in the new_paper.md file with the url parameter. For instance, with url: /paperx/, the URL of the new paper is simplified to baseURL/paperx/.

  • New categories

It is also easy to add new categories to the website, for instance to list software, data, a blog, and so on. For instance to add a list of datasets, create a new data subfolder into the content folder. Then add a content file such as new_dataset.md into the data subfolder. That new category will be available at baseURL/data/. You can for instance link to it with a button from the homepage. To do that, simply add the following snippet into the config.yml file, below profileMode:buttons:

1
2

- name: Datasets
  url: /data/

You can also add a link to the new category in the menu bar. To do that, simply add the following snippet into the config.yml file, below menu:main:

1
2
3

- name: Datasets
  url: /data/
  weight: 4

Static files

The static folder contains all the static files (files not processed or rendered by Hugo) for the website. These include all the PDF files and images to which the website links.

Tags

The tags are accessible from the menu bar. Tags can be added to any webpage with the tags parameter. The tag page is generated by default, but it can be customized through the file _index.md placed in the content/tag/ folder. The file defines for instance the description of the page for search engines (description:) as well as the title of the page (title:).

Archetypes

The template comes with archetypes, stored in the archetypes folder. In Hugo, an archetype is a predefined content template that serves as a blueprint for creating new pages. Archetypes help streamline content creation by providing a consistent starting point with predefined metadata and content structure. There is an archetype for paper pages (paper.md) and an archetype for course pages (course.md)

To create a new webpage from an archetype, simply use the hugo new command in the terminal from the website directory. For example, to create a page for a new course, you can run:

hugo new content/courses/my-new-teaching-material.md --kind course

Hugo will generate a new content file called my-new-teaching-material.md and place it the directory content/courses/, where all the courses are stored. Furthermore, Hugo will use the archetype course.md. Then, you can edit the content of the page by modifying the newly created file my-new-teaching-material.md.

Archive

An archive can be added to the website. The archive displays a chronological list of all papers, courses, and design projects.

To add an archive page, move the archive.md file from the archetypes folder into the content folder. Then, add the following snippet below in the config.yml file to make the archive available from the menu:

1
2
3

- name: Archive
  url: /archive/
  weight: 7

The archive will be available at baseURL/archive/.

Search page

A search page can also be added to the website. To add a search page, move the search.md file from the archetypes folder into the content folder. Then, add the following snippet at the end of the config.yml file so that search works properly:

1
2
3
4
5

outputs:
     home:
         - HTML
         - RSS
         - JSON

Finally, add the following snippet below in the config.yml file to make the search page available from the menu:

1
2
3

- name: Search
  url: /search/
  weight: 6

The search page will be available at baseURL/search/.

The website does not have a footer, but it is possible to add one by setting hideFooter: false in the config.yml file. The footer contains a copyright notice and a “powered by” notice. The footer can be customized by modifying the file layouts/partials/footer.html.

Public folder

The public folder contains the fully generated static website files that are ready to be deployed to GitHub Pages. When you run the hugo command, Hugo processes your content, templates, and other project files and generates a static website. The resulting output is placed in the public folder by default.

The public folder can always be safely deleted. A new version of the public folder will be created when you run the hugo command in the terminal.