Notes on Hugo for Beginners (and Me), Part 2, Building Blocks

In part 1 of this series I covered what it takes to create a post using Hugo. This post covers the structure of the files that make up the site and allow a post to be published on the site.

Directories

When a new Hugo site is created, a small number of directories are created. These are described in the formal documentation but I have my own descriptions below:

• archetypes - stores the default files and file bundles used when new content is created
• config - contains the config files - this one I added so I could split the config settings across different files
• content - contains all of the user created content
• data - if used, contains data files
• layouts - contains the files used to layout the site and provide shortcodes
• static - files that are not changed and served as is
  • favicons - contains the favicons files
  • images - image files
• themes - contains a folder for each theme and theme component used on the site

Core Directories

Several of these directories are essential to understand as they contain the core building blocks of a Hugo site.

content

This directory stores the user created content including folders for particular types of content and root level pages. In my content directory I have the following structure:

• posts - contains all of my posts in folders for each year
  • YYYY - a folder for each year
    • YYYY-MM-DD-post-title - a folder for each post
      • index.md - the page that contains the content for each post
• about.md - a page containing the content for the about section
• community.md - a page containing the content for the about section
• search.md - a page providing the search capabilities

layouts

The layouts directory contains the templates used to covnert the markdown files into HTML. There is defined lookup order that Hugo uses to find the right template file based on the type of page.

The core purpose of the folders is shown below:

• _default - if no match is found anywhere else, this is the location that will be used
• partials - this contains HTML snippets which are used to layout the pages and provide features such as navigation, table of contents or other custom content that needs to be reused. The partials can be used in HTML files that are in the layouts directory
• shortcodes - like partials but are run from the mardown files in the content directory

static

The static directory stores files that are not transformed and are served as they are. The folders that I have added are:

• favicons - contains all favicon files
• images - static images used on my site include the profile picture

themes

This folder is where theme projects and theme components are stored. These are usually included as cloned GitHub solutions.

Customised Page Layouts

The structure of the Hugo directories is key to the lookup order for particular files, and it allows for customisations based on new folders and files placed in particular locations.

The layouts\_default directory contains default files for displaying particular types of content:

• single.html - displays a single item
• list.html - displays a list of items
• terms.html - displays a list of terms in a taxonomy
• taxonomy.html - display details of a term and content with the tag

New templates can be added in directories that are named the same as the direcorites in the content directory, e.g. add the following to create a new custom layout for posts:

• content\posts\
• layouts\posts\
  • single.html
  • lists.html

Summary

This post covers the basics of the structure of the directories and files that are used in a Hugo site. Themes provide another layer of customisation and they provide a quick way to ensure that a Hugo site works well and looks good.

The order of lookup of files ensures that there ways to customise content based on where files are located and what their name is.