HUGO

  • News
  • Docs
  • Themes
  • Community
  • GitHub
Star

What's on this Page

    • Organization of Content Source
    • Path Breakdown in Hugo
      • Index Pages: _index.md
      • Single Pages in Sections
      • Section with Nested Directories
    • Paths Explained
      • section
      • slug
      • path
      • url
    • Override Destination Paths via Front Matter
      • filename
      • slug
      • section
      • type
      • url
CONTENT MANAGEMENT FUNDAMENTALS

Content Organization

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

This section is not updated with the new nested sections support in Hugo 0.24, see https://github.com/gohugoio/hugoDocs/issues/36

Organization of Content Source

In Hugo, your content should be organized in a manner that reflects the rendered website.

While Hugo supports content nested at any level, the top levels (i.e. content/<DIRECTORIES>) are special in Hugo and are considered the content sections. Without any additional configuration, the following will just work:

.
└── content
    └── about
    |   └── _index.md  // <- https://example.com/about/
    ├── post
    |   ├── firstpost.md   // <- https://example.com/post/firstpost/
    |   ├── happy
    |   |   └── ness.md  // <- https://example.com/post/happy/ness/
    |   └── secondpost.md  // <- https://example.com/post/secondpost/
    └── quote
        ├── first.md       // <- https://example.com/quote/first/
        └── second.md      // <- https://example.com/quote/second/

Path Breakdown in Hugo

The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are using pretty URLs, which is the default behavior for Hugo. The examples also assume a key-value of baseurl = "https://example.com" in your site’s configuration file.

Index Pages: _index.md

_index.md has a special role in Hugo. It allows you to add front matter and content to your list templates as of v0.18. These templates include those for section templates, taxonomy templates, taxonomy terms templates, and your homepage template. In your templates, you can grab information from _index.md using the .Site.GetPage function.

You can keep one _index.md for your homepage and one in each of your content sections, taxonomies, and taxonomy terms. The following shows typical placement of an _index.md that would contain content and front matter for a posts section list page on a Hugo website:

.         url
.       ⊢--^-⊣
.        path    slug
.       ⊢--^-⊣⊢---^---⊣
.           filepath
.       ⊢------^------⊣
content/posts/_index.md

At build, this will output to the following destination with the associated values:


                     url ("/posts/")
                    ⊢-^-⊣
       baseurl      section ("posts")
⊢--------^---------⊣⊢-^-⊣
        permalink
⊢----------^-------------⊣
https://example.com/posts/index.html

Single Pages in Sections

Single content files in each of your sections are going to be rendered as single page templates. Here is an example of a single post within posts:

                   path ("posts/my-first-hugo-post.md")
.       ⊢-----------^------------⊣
.      section        slug
.       ⊢-^-⊣⊢--------^----------⊣
content/posts/my-first-hugo-post.md

At the time Hugo builds your site, the content will be output to the following destination:


                               url ("/posts/my-first-hugo-post/")
                   ⊢------------^----------⊣
       baseurl     section     slug
⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣
                 permalink
⊢--------------------^---------------------⊣
https://example.com/posts/my-first-hugo-post/index.html

Section with Nested Directories

To continue the example, the following demonstrates destination paths for a file located at content/events/chicago/lollapalooza.md in the same site:

                    section
                    ⊢--^--⊣
                               url
                    ⊢-------------^------------⊣

      baseURL             path        slug
⊢--------^--------⊣ ⊢------^-----⊣⊢----^------⊣
                  permalink
⊢----------------------^-----------------------⊣
https://example.com/events/chicago/lollapalooza/

As of v0.20, Hugo does not recognize nested sections. While you can nest as many content directories as you’d like, any child directory of a section will still be considered the same section as that of its parents. Therefore, in the above example, {{.Section}} for lollapalooza.md is events and not chicago. See the related issue on GitHub.

Paths Explained

The following concepts will provide more insight into the relationship between your project’s organization and the default behaviors of Hugo when building the output website.

section

A default content type is determined by a piece of content’s section. section is determined by the location within the project’s content directory. section cannot be specified or overridden in front matter.

slug

A content’s slug is either name.extension or name/. The value for slug is determined by

  • the name of the content file (e.g., lollapalooza.md) OR
  • front matter overrides

path

A content’s path is determined by the section’s path to the file. The file path

  • is based on the path to the content’s location AND
  • does not include the slug

url

The url is the relative URL for the piece of content. The url

  • is based on the content’s location within the directory structure OR
  • is defined in front matter and overrides all the above

Override Destination Paths via Front Matter

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 where you may need more control over your content. In these cases, there are fields that can be specified in the front matter to determine the destination of a specific piece of content.

The following items are defined in this order for a specific reason: items explained further down in the list will override earlier items, and not all of these items can be defined in front matter:

filename

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 (e.g., content/posts/my-post.md becomes example.com/posts/my-post/).

slug

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

content/posts/old-post.md

---
title: New Post
slug: "new-post"
---

This will render to the following destination according to Hugo’s default behavior:

example.com/posts/new-post/

section

section is determined by a content’s location on disk and cannot be specified in the front matter. See sections for more information.

type

A content’s type is also determined by its location on disk but, unlike section, it can be specified in the front matter. See types. This can come in especially handy when you want a piece of content to render using a different layout. In the following example, you can create a layout at layouts/new/mylayout.html that Hugo will use to render this piece of content, even in the midst of many other posts.

content/posts/my-post.md

---
title: My Post
type: new
layout: mylayout
---

url

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 /). url will be used exactly as it provided in the front matter and will ignore the --uglyURLs setting in your site configuration:

content/posts/old-url.md

---
title: Old URL
url: /blog/new-url/
---

Assuming your baseURL is configured to https://example.com, the addition of url to the front matter will make old-url.md render to the following destination:

https://example.com/blog/new-url/

You can see more information on how to control output paths in URL Management.

See Also

  • Comments
  • Content Types
  • Content Sections
  • Related Content
  • .GetPage
  • About Hugo
    • Overview
    • Hugo Features
    • The Benefits of Static
    • Roadmap
    • License
  • Getting Started
    • Get Started Overview
    • Quick Start
    • Install Hugo
    • Basic Usage
    • Directory Structure
    • Configuration
  • Themes
    • Themes Overview
    • Install and Use Themes
    • Customize a Theme
    • Create a Theme
  • Content Management
    • Content Management Overview
    • Organization
    • Supported Content Formats
    • Front Matter
    • Shortcodes
    • Related Content
    • Sections
    • Types
    • Archetypes
    • Taxonomies
    • Summaries
    • Links and Cross References
    • URL Management
    • Menus
    • Table of Contents
    • Comments
    • Multilingual and i18n
    • Syntax Highlighting
  • Templates
    • Templates Overview
    • Introduction
    • Template Lookup Order
    • Custom Output Formats
    • Base Templates and Blocks
    • List Page Templates
    • Homepage Template
    • Section Templates
    • Taxonomy Templates
    • Single Page Templates
    • Content View Templates
    • Data Templates
    • Partial Templates
    • Shortcode Templates
    • Local File Templates
    • 404 Page
    • Menu Templates
    • Pagination
    • RSS Templates
    • Sitemap Template
    • Robots.txt
    • Internal Templates
    • Alternative Templating
    • Template Debugging
  • Functions
    • Functions Quick Reference
    • .AddDate
    • .Format
    • .Get
    • .GetPage
    • .Param
    • .Scratch
    • .Unix
    • Math
    • absLangURL
    • absURL
    • after
    • apply
    • base64
    • chomp
    • countrunes
    • countwords
    • dateFormat
    • default
    • delimit
    • dict
    • echoParam
    • emojify
    • eq
    • findRE
    • first
    • ge
    • getenv
    • gt
    • hasPrefix
    • highlight
    • htmlEscape
    • htmlUnescape
    • humanize
    • i18n
    • imageConfig
    • in
    • index
    • int
    • intersect
    • isset
    • jsonify
    • lang.NumFmt
    • last
    • le
    • lower
    • lt
    • markdownify
    • md5
    • ne
    • now
    • partialCached
    • plainify
    • pluralize
    • print
    • printf
    • println
    • querify
    • range
    • readDir
    • readFile
    • ref
    • relLangURL
    • relURL
    • relref
    • render
    • replace
    • replaceRE
    • safeCSS
    • safeHTML
    • safeHTMLAttr
    • safeJS
    • safeURL
    • seq
    • sha
    • shuffle
    • singularize
    • slice
    • slicestr
    • sort
    • split
    • string
    • strings.TrimLeft
    • strings.TrimPrefix
    • strings.TrimRight
    • strings.TrimSuffix
    • substr
    • time
    • title
    • trim
    • truncate
    • union
    • uniq
    • upper
    • urlize
    • urls.Parse
    • where
    • with
  • Variables
    • Variables Overview
    • Site Variables
    • Page Variables
    • Shortcode Variables
    • Taxonomy Variables
    • File Variables
    • Menu Variables
    • Hugo Variables
    • Git Variables
    • Sitemap Variables
  • CLI
  • Troubleshooting
    • Troubleshoot
    • Accented Characters in URLs
    • Build Performance
    • EOF Error
  • Tools
    • Developer Tools Overview
    • Migrations
    • Starter Kits
    • Frontends
    • Editor Plug-ins
    • Search
    • Other Projects
  • Hosting & Deployment
    • Hosting & Deployment Overview
    • Host-Agnostic Deploys with Nanobox
    • Host on Netlify
    • Host on Firebase
    • Host on GitHub
    • Host on GitLab
    • Host on Bitbucket
    • Deployment with Wercker
    • Deployment with Rsync
  • Contribute
    • Contribute to Hugo
    • Development
    • Documentation
    • Themes
“Content Organization” was last updated: October 13, 2017: Initial commit (a48229f)
Improve this page
By the Hugo Authors

The Hugo logos are copyright © Steve Francia 2013–2017.

The Hugo Gopher is based on an original work by Renée French.

  • File an Issue
  • Get Help
  • Discuss the Source Code
  • @GoHugoIO
  • @spf13
  • @bepsays
  • News
  • Docs
  • Themes
  • Community
  • GitHub
  • About Hugo
  • Getting Started
  • Themes
  • Content Management
  • Templates
  • Functions
  • Variables
  • CLI
  • Troubleshooting
  • Tools
  • Hosting & Deployment
  • Contribute