The Hugo Directory Structure and Its Implication for the Website Organization

The markup files with the main content of the website are stored under /content. Hugo recognizes which input format is used by their file extension.

As a rule, each markup file in this directory corresponds to its own page. The word page is to be understood here in a general sense, which also includes things like blog posts or overview pages for categories or keywords.

Hugo is a static site generator, which means that static pages are automatically created from hand-written files during the build process. The previously discussed markup files in the content/ directory serve as the main input. The output that is created from markup and layout files is stored in the public/ directory and consists of files that are eventually served to visitors on request as a web page.

How the build engine organizes the static outputs has implications for how singular pages of the website are to be accessed. The directory structure under public/ corresponds exactly to the structure under content/. For example, if a file is located under content/blog/post-1.md, the build engine creates an HTML output under public/blog/post-1.html when processing this file.

In practical terms, this means that there is a one-to-one relation between the components of file paths and the components of the URLs used to access the content created. An example illustrates this point: If the main content of a page is written in Markdown and saved in a file under content/blog/post-1.md, the page can be accessed under domain.com/blog/post-1/.

This basic principle is summed up in the official documentation in the following way:

Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site.

In this way, Hugo avoids complex routing definitions that you may be familiar with from other frameworks. Consequently, end users have one less thing to worry about.

In principle, it is possible to define your own URLs for our content. To do this, certain keys are set in the front matter or the main configuration. The procedure involves some additional work, but can be important in some scenarios.

In addition to the main content, websites include other components and information. They are not defined under content/, but as layouts/. Their main purpose is to insert metadata or reusable components such as headers and footers into the generated HTML.

The difference is therefore that main content is page-specific, while layouts and templates tend to be reusable. The website organization depends solely on the main content and its file organization.