Introduction
All the files for a website are organized in folders within a project folder. [1]
The target web site is created in the public folder. The
templates are in the layouts folder.
The source text is in the content folder and its subfolders, in
.md, .json or .html files. The .md files have a block
with metadata in their first lines, in YAML, TOML or JSON format. This
block provides variables that can be used in the templates and in hugo
it is called front matter.
The images, audios, videos, JavaScript and CSS are usually stored in
the static folder. These files and folders are copied without the
static prefix into public.
The required config.toml file configures variables or overrides
default values of the website.
Generation
Hugo explores the hierarchy inside the content folder. It selects
a template for each content file found and generates the corresponding
folders and .html files in public.
Leaf nodes
If a folder contains an index.md file, the single.html
template is selected to generate the index.html file for that
folder in the destination. If there is an index.html file it is
only copied. If there are other .md files in that folder, the
single.html template is also used to generate the .html file
that corresponds to each .md.
Branch nodes
If there is a _index.md file in a folder, the list.html
template is selected to generate the index.html for that folder in
the destination.
[2]
If there are other .md files in that folder, the
single.html template is selected to generate an .html file
based on each .md file.
A list.html template usually lists and links to the pages that
correspond to the other .md files in that folder. list.html
may use variables from the metadata block of each listed page.
Templates
The default templates are in the layouts/_default/ folder. They
may be overriden by a template with identical name in the
layouts/<section> folder, where section is the name of the
first-level folder where the .md file is.
If a theme is used, its templates are inside the
themes/name/layouts folder. The theme templates can be overriden
by a template with identical name and path under the layouts
folder.