Content Organization

Hugo uses files (see supported formats) with headers commonly called the front matter. Hugo respects the organization that you provide for your content to minimize any extra configuration, though this can be overridden by additional configuration in the front matter.


In Hugo, the content should be arranged in the same way they are intended for the rendered website. Without any additional configuration, the following will just work. Hugo supports content nested at any level. The top level is special in Hugo and is used as the section.

└── content
    ├── post
    |   ├──   // <-
    |   ├── happy
    |   |   └──  // <-
    |   └──  // <-
    └── quote
        ├──       // <-
        └──      // <-

Here’s the same organization run with hugo --uglyURLs

└── content
    ├── post
    |   ├──   // <-
    |   ├── happy
    |   |   └──    // <-
    |   └──  // <-
    └── quote
        ├──       // <-
        └──      // <-


Hugo believes that you organize your content with a purpose. The same structure that works to organize your source content is used to organize the rendered site. As displayed above, the organization of the source content will be mirrored in the destination.

There are times when one would need more control over their content. In these cases, there are a variety of things that can be specified in the front matter to determine the destination of a specific piece of content.

The following items are defined in order, latter items in the list will override earlier settings.


This isn’t in the front matter, but is the actual name of the file minus the extension. This will be the name of the file in the destination.


Defined in the front matter, the slug can take the place of the filename for the destination.


The actual path to the file on disk. Destination will create the destination with the same path. Includes section.


section is determined by its location on disk and can not be specified in the front matter. See section.


type is also determined by its location on disk but, unlike section, it can be specified in the front matter. See type.


path can be provided in the front matter. This will replace the actual path to the file on disk. Destination will create the destination with the same path. Includes section.


A complete URL can be provided. This will override all the above as it pertains to the end destination. This must be the path from the baseURL (starting with a “/”). When a url is provided, it will be used exactly. Using url will ignore the --uglyURLs setting.

Path breakdown in Hugo


.             path           slug
.       ⊢-------^----⊣ ⊢------^-------⊣

.       section              slug
.       ⊢--^--⊣        ⊢------^-------⊣

.       section  slug
.       ⊢--^--⊣⊢--^--⊣



   baseURL       section  slug
⊢-----^--------⊣ ⊢--^---⊣ ⊢-^⊣

   baseURL       section          slug
⊢-----^--------⊣ ⊢--^--⊣        ⊢--^--⊣

   baseURL            path       slug
⊢-----^--------⊣ ⊢------^-----⊣ ⊢--^--⊣

   baseURL            url
⊢-----^--------⊣ ⊢-----^-----⊣

   baseURL               url
⊢-----^--------⊣ ⊢--------^-----------⊣

section = which type the content is by default

  • based on content location
  • front matter overrides

slug = name.ext or name/

  • based on
  • front matter overrides

path = section + path to file excluding slug

  • based on path to content location

url = relative URL

  • defined in front matter
  • overrides all the above