hugo/docs/content/content-management/sections.md

3.8 KiB

title linktitle description date publishdate lastmod categories menu weight draft aliases toc
Content Sections Sections Hugo supports content sections, which according to Hugo's default behavior, will reflect the structure of the rendered website. 2017-02-01 2017-02-01 2017-02-01
content management
docs
parent weight
content-management 50
50 false
/content/sections/
true

{{% note %}} This section is not updated with the new nested sections support in Hugo 0.24, see https://github.com/gohugoio/hugoDocs/issues/36 {{% /note %}} {{% todo %}} See above {{% /todo %}}

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 (see directory structure).

Following this pattern, Hugo uses the top level of your content organization as the content section.

The following example shows a content directory structure for a website that has three sections: "authors," "events," and "posts":

.
└── content
    ├── authors
    |   ├── _index.md     // <- example.com/authors/
    |   ├── john-doe.md   // <- example.com/authors/john-doe/
    |   └── jane-doe.md   // <- example.com/authors/jane-doe/
    └── events
    |   ├── _index.md     // <- example.com/events/
    |   ├── event-1.md    // <- example.com/events/event-1/
    |   ├── event-2.md    // <- example.com/events/event-2/
    |   └── event-3.md    // <- example.com/events/event-3/
    └── posts
    |   ├── _index.md     // <- example.com/posts/
    |   ├── event-1.md    // <- example.com/posts/event-1/
    |   ├── event-2.md    // <- example.com/posts/event-2/
    |   ├── event-3.md    // <- example.com/posts/event-3/
    |   ├── event-4.md    // <- example.com/posts/event-4/
    |   └── event-5.md    // <- example.com/posts/event-5/

Content Section Lists

Hugo will automatically create pages for each section root that list all of the content in that section. See the documentation on section templates for details on customizing the way these pages are rendered.

As of Hugo v0.18, section pages can also have a content file and front matter. These section content files must be placed in their corresponding section folder and named _index.md in order for Hugo to correctly render the front matter and content.

{{% warning "index.md vs _index.md" %}} Hugo themes developed before v0.18 often used an index.md(i.e., without the leading underscore [_]) in a content section as a hack to emulate the behavior of _index.md. The hack may work...sometimes; however, the order of page rendering can be unpredictable in Hugo. What works now may fail to render appropriately as your site grows. It is strongly advised to use _index.md as content for your section index pages. Note: _index.md's layout, as representative of a section, is a list page template and not a single page template. If you want to alter the new default behavior for _index.md, configure disableKinds accordingly in your site's configuration. {{% /warning %}}

Content Section vs Content Type

By default, everything created within a section will use the content type that matches the section name. For example, Hugo will assume that posts/post-1.md has a posts content type. If you are using an archetype for your posts section, Hugo will generate front matter according to what it finds in archetypes/posts.md.