Notes on Hugo for Beginners (and Me), Part 2, Building Blocks
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
Several of these directories are essential to understand as they contain the core building blocks of a Hugo site.
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 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
shortcodes- like partials but are run from the mardown files in 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
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.
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:
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.