How Websites Are Structured in Hugo

There is a pattern to the way that websites are structured. We will define degrees of complexity, and introduce the features that Hugo provides to deal with this complexity.

A central aspect of managing content in Hugo is the assignment of kinds and types. The assignment is usually based on the file names and the position of the files within the directory tree. Type membership is important, because it determines what layout is applied to the main content. Kinds and types also play an essential role when new content is created using archetypes.

In this part of the series, we provide an overview of the types that Hugo assigns by default. Later on, we will also explain how to assign types manually.

Flat Hierarchies

Let’s start with the simplest case. A one-pager refers to websites that only have a single main page. In Hugo, the main content of this page is stored in the file content/_index.md. This homepage can be accessed via the base URL, e.g. https://example.com/. Since it’s of the kind home, the home layout is applied to it.

Many websites comprise several individual pages that exist independently of each other. On the website of a craft business, for example, there may be subpages such as Home, Services, About us and Contact. In Hugo, a separate markup file is created for each of these pages in the content/ directory, such as content/services.md. These pages are treated as single pages, to which the kind page is assigned. They use the single layout.

Single pages are to be distinguished from overview pages, which list individual pages and are hence also referred to as list pages. While more differentiated kinds are commonly assigned to them (more on this in a moment), a list layout can be defined as a fallback.

In addition, Hugo distinguishes special kinds of individual pages: 404 for a 404 error page, sitemap for the sitemap.xml, and robotstxt for the robots.txt. These pages are generated automatically and can be designed using layouts with the same name.

Sections

There is main content that is not suitably placed in the main navigation. Blog posts are a typical example, as are newspaper articles or tutorials on a tech portal. Such content represents specific types of single pages—blog posts, articles, or tutorials.

In this context, Hugo speaks of sections of the website. These are areas whose content usually fits together thematically or stylistically. In practice, they are defined by creating direct or indirect subdirectories in the content/ folder. There are two basic cases.

If a directory is created directly under content/, this results in a single page type of the same name. Types behave similarly to kinds, but are somewhat more specific. For example, the content of content/blog/post-1.md is of the kind page and of the type blog. It follows that the blog layout is used for post-1.md; only if this layout does not exist, it will fall back to a single layout. This also applies to content at lower levels. Thus, content/blog/2024/post-1.md is also a blog post.

Directories located at lower levels of the directory tree represent a section of the website if they contain a file called _index.md. This markup file usually creates an overview page. For example, content/blog/_index.md would generate a page that lists blog posts and is accessed via domain.com/blog/.

There is a wide range of ways you may define a section layout, though these are probably the most likely to exist (in order of precedence): layouts/blog/list.html, layouts/_default/blog.html, layouts/_default/section.html. Or even the very general layout/_default/list.html, which functions as fallback not only for sections, but for other overview pages, too (like for taxonomies, for instance).

Section Overview Pages

Directories directly under content/ may contain an _index.md. Unlike sections of the other kind, however, this does not determine whether a corresponding overview page is available. If not explicitly deactivated (more on this in a moment), Hugo automatically creates an overview page for all top-level sections.

However, this is not always what we want. To illustrate, let’s consider the blog section. Instead of presenting all blog posts on one page, we may want to structure them by year of publication. In this case, we would create content/blog/2024/_index.md and content/blog/2023/_index.md to generate overview pages for the lower level sections.

However, by default Hugo would still create domain.com/blog/. If we do not want this, content/blog/_index.md can be used to deactivate the overview page.

---
title: "Blog"
_build:
  render: never
  list: never
---

This setting has the effect that domain.com/blog/ leads to the 404 error page, while domain.com/blog/2023/ and domain.com/blog/2024/ remain accessible.

Sections are helpful to systematically present the content of a certain type to visitors, especially if there is a lot of content of that type. In other scenarios, where lower level subdirectories do not have the _index.md, they are only used to structure file paths and URLs.

Deactivating Sections

If no sections are required on the website, the feature can be deactivated globally in the main configuration:

disableKinds: ['section']

This means that automatic overview pages are no longer created for top-level sections. However, if we still want to use an overview page we can create an _index.md.

Deactivating sections has practical consequences, of course. Some features can then no longer be used, including specific layouts (under layouts/SECTION/), custom template variables (.Section and .CurrentSection) and Section menus.

Incidentally, other kinds of automatically created content can be deactivated in this way. Of the types already mentioned, these are: 404, home, page, robotstxt, rss and sitemap. In the context of tagging, two further types will be discussed.