Skip to content

Commit

Permalink
Update sections page
Browse files Browse the repository at this point in the history
  • Loading branch information
@jmooring
jmooring authored Aug 25, 2023
1 parent ed35fc6 commit a51bf9f
Show file tree
Hide file tree
Showing 5 changed files with 154 additions and 105 deletions.
152 changes: 110 additions & 42 deletions content/en/content-management/sections.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
title: Sections
description: Hugo generates a **section tree** that matches your content.
description: Organize content into sections.

categories: [content management]
keywords: [lists,sections,content types,organization]
menu:
Expand All @@ -12,54 +13,112 @@ weight: 120
aliases: [/content/sections/]
---

A **Section** is a collection of pages that gets defined based on the
organization structure under the `content/` directory.

By default, all the **first-level** directories under `content/` form their own
sections (**root sections**) provided they constitute [Branch Bundles][branch bundles].
Directories which are just [Leaf Bundles][leaf bundles] do *not* form
their own sections, despite being first-level directories.

If a user needs to define a section `foo` at a deeper level, they need to create
a directory named `foo` with an `_index.md` file (see [Branch Bundles][branch bundles]
for more information).
## Overview

A section is a top-level content directory, or any content directory with an _index.md file. A content directory with an _index.md file is also known as a [branch bundle](/getting-started/glossary/#branch-bundle). Section templates receive one or more page [collections](/getting-started/glossary/#collection) in [context](/getting-started/glossary/#context).

{{% note %}}
A **section** cannot be defined or overridden by a front matter parameter -- it
is strictly derived from the content organization structure.
Although top-level directories without _index.md files are sections, we recommend creating _index.md files in _all_ sections.
{{% /note %}}

## Nested sections
A typical site consists of one or more sections. For example:

```text
content/
├── articles/ <-- section (top-level directory)
│   ├── 2022/
│   │   ├── article-1/
│   │   │   ├── cover.jpg
│   │   │   └── index.md
│   │   └── article-2.md
│   └── 2023/
│   ├── article-3.md
│   └── article-4.md
├── products/ <-- section (top-level directory)
│   ├── product-1/ <-- section (has _index.md file)
│   │   ├── benefits/ <-- section (has _index.md file)
│   │   │   ├── _index.md
│   │   │   ├── benefit-1.md
│   │   │   └── benefit-2.md
│   │   ├── features/ <-- section (has _index.md file)
│   │   │   ├── _index.md
│   │   │   ├── feature-1.md
│   │   │   └── feature-2.md
│   │   └── _index.md
│   └── product-2/ <-- section (has _index.md file)
│   ├── benefits/ <-- section (has _index.md file)
│   │   ├── _index.md
│   │   ├── benefit-1.md
│   │   └── benefit-2.md
│   ├── features/ <-- section (has _index.md file)
│   │   ├── _index.md
│   │   ├── feature-1.md
│   │   └── feature-2.md
│   └── _index.md
├── _index.md
└── about.md
```

The sections can be nested as deeply as you need.
The example above has two top-level sections: articles and products. None of the directories under articles are sections, while all of the directories under products are sections. A section within a section is a known as a nested section or subsection.

```bash
content
└── blog <-- Section, because first-level dir under content/
├── funny-cats
│   ├── mypost.md
│   └── kittens <-- Section, because contains _index.md
│   └── _index.md
└── tech <-- Section, because contains _index.md
└── _index.md
```
## Explanation

**The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (e.g. `_index.md`).**
Sections and non-sections behave differently.

{{% note %}}
When we talk about a **section** in correlation with template selection, it is
currently always the *root section* only (`/blog/funny-cats/mypost/ => blog`).
||Sections|Non-sections
:--|:-:|:-:
Directory names become URL segments|:heavy_check_mark:|:heavy_check_mark:
Have logical ancestors and descendants|:heavy_check_mark:|:x:
Have list pages|:heavy_check_mark:|:x:

If you need a specific template for a sub-section, you need to adjust either the `type` or `layout` in front matter.
{{% /note %}}
With the file structure from the [example above](#overview):

1. The list page for the articles section includes all articles, regardless of directory structure; none of the subdirectories are sections.

1. The articles/2022 and articles/2023 directories do not have list pages; they are not sections.

1. The list page for the products section, by default, includes product-1 and product-2, but not their descendant pages. To include descendant pages, use the `.RegularPagesRecursive` collection instead of the `.Pages` collection in the list template. See [details](/variables/page/#page-collections).

1. All directories in the products section have list pages; each directory is a section.

## Template selection

Hugo has a defined [lookup order] to determine which template to use when rendering a page. The [lookup rules] consider the top-level section name; subsection names are not considered when selecting a template.

## Example: breadcrumb navigation
With the file structure from the [example above](#overview):

With the available [section variables and methods](#section-page-variables-and-methods) you can build powerful navigation. One common example would be a partial to show Breadcrumb navigation:
Content directory|List page template
:--|:--
content/products|layouts/products/list.html
content/products/product-1|layouts/products/list.html
content/products/product-1/benefits|layouts/products/list.html

Content directory|Single page template
:--|:--
content/products|layouts/products/single.html
content/products/product-1|layouts/products/single.html
content/products/product-1/benefits|layouts/products/single.html

If you need to use a different template for a subsection, specify `type` and/or `layout` in front matter.

[lookup rules]: /templates/lookup-order/#lookup-rules
[lookup order]: /templates/lookup-order/

## Ancestors and descendants

A section has one or more ancestors (including the home page), and zero or more descendants. With the file structure from the [example above](#overview):


```text
content/products/product-1/benefits/benefit-1.md
```

The content file (benefit-1.md) has four ancestors: benefits, product-1, products, and the home page. This logical relationship allows us to use the `.Parent` and `.Ancestors` methods to traverse the site structure.

For example, use the `.Ancestors` method to render breadcrumb navigation.

{{< code file="layouts/partials/breadcrumb.html" >}}
<nav aria-label="breadcrumb">
<nav aria-label="breadcrumb" class="breadcrumb">
<ol>
{{ range .Ancestors.Reverse }}
<li>
Expand All @@ -73,19 +132,28 @@ With the available [section variables and methods](#section-page-variables-and-m
</nav>
{{< /code >}}

## Section page variables and methods
With this CSS:

Also see [Page Variables](/variables/page/).
```css
.breadcrumb ol {
padding-left: 0;
}

{{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}}
.breadcrumb li {
display: inline;
}

## Content section lists
.breadcrumb li:not(:last-child)::after {
content: "»";
}
```

Hugo will automatically create a page for each *root section* that lists all the content in that section. See the documentation on [section templates] for details on customizing the way these pages are rendered.
The result is something like:

## Content *section* vs. content *type*
```text
Home » Products » Product 1 » Benefits » Benefit 1
```

By default, everything created within a section will use the [content `type`][content type] that matches the *root 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`.

[archetype]: /content-management/archetypes/
[content type]: /content-management/types/
Expand Down
24 changes: 22 additions & 2 deletions content/en/getting-started/glossary.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ A data type with two possible values, either `true` or `false`.

### branch bundle

A [page bundle](#page-bundle) with an _index.md file and zero or more [resources](#resource). Analogous to a physical branch, a branch bundle may have descendants including regular pages, [leaf bundles](/getting-started/glossary/#leaf-bundle), and other branch bundles. See [details](/content-management/page-bundles/).
A [page bundle](#page-bundle) with an&nbsp;_index.md file and zero or more [resources](#resource). Analogous to a physical branch, a branch bundle may have descendants including regular pages, [leaf bundles](/getting-started/glossary/#leaf-bundle), and other branch bundles. See [details](/content-management/page-bundles/).

### build

Expand Down Expand Up @@ -112,6 +112,10 @@ See [template](#template).

A [page bundle](#page-bundle) with an index.md file and zero or more [resources](#resource). Analogous to a physical leaf, a leaf bundle is at the end of a branch. Hugo ignores content (but not resources) beneath the leaf bundle. See [details](/content-management/page-bundles/).

### list page

Any [page kind](#page-kind) that receives a page [collection](#collection) in [context](#context). This includes the home page, [section pages](#section-page), [taxonomy pages](#taxonomy-page), and [term pages](#term-page).

### localization

Adaptation of a site to meet language and regional requirements. This includes translations, language-specific media, date and currency formats, etc. See [details](/content-management/multilingual/) and the [W3C definition](https://www.w3.org/International/questions/qa-i18n). Abbreviated l10n.
Expand Down Expand Up @@ -178,6 +182,10 @@ A pipeline may be *chained* by separating a sequence of commands with pipeline c

See [build](#build).

### regular page

Content with the "page" [page kind](#page-kind). See also [section page](#section-page).

### render hook

A [template](#template) that overrides standard markdown rendering. See [details](/templates/render-hooks/).
Expand All @@ -194,7 +202,11 @@ A single value, one of [string](#string), [integer](#integer), [floating point](

### section

A directory of content pages with an _index.md file. A section may contain subdirectories without _index.md files. An _index.md file is optional in top-level directories. Section templates receive one or more page [collections](#collection) in [context](#context). See [details](/templates/lists/).
A top-level content directory, or any content directory with an&nbsp;_index.md file. A content directory with an&nbsp;_index.md file is also known as a [branch bundle](/getting-started/glossary/#branch-bundle). Section templates receive one or more page [collections](#collection) in [context](#context). See [details](/content-management/sections/).

### section page

Content with the "section" [page kind](#page-kind). Typically a listing of [regular pages](#regular-page) and/or [section pages](#section-page) within the current [section](#section). See also [regular page](#regular-page).

### shortcode

Expand All @@ -212,6 +224,10 @@ A sequence of bytes. For example, `"What is 6 times 7?"`&nbsp;.

A group of related [terms](#term) used to classify content. For example, a "colors" taxonomy might include the terms "red", "green", and "blue". See&nbsp;[details](/content-management/taxonomies/).

### taxonomy page

Content with the "taxonomy" [page kind](#page-kind). Typically a listing of [terms](#term) within a given [taxonomy](#taxonomy).

### template

An HTML file with [template actions](#template-action), located within the layouts directory of a project, theme, or module. See&nbsp;[details](/templates/).
Expand All @@ -224,6 +240,10 @@ A data evaluation or control structure within a [template](#template), delimited

A member of a [taxonomy](#taxonomy), used to classify content. See&nbsp;[details](/content-management/taxonomies/).

### term page

Content with the "term" [page kind](#page-kind). Typically a listing of [regular pages](#regular-page) and [section pages](#section-page) with a given [term](#term).

### theme

A packaged combination of [archetypes](#archetype), assets, content, data, [templates](#template), translations, or configuration settings. A theme may serve as the basis for a new site, or to augment an existing site. See also [module](#module).
Expand Down
34 changes: 0 additions & 34 deletions content/en/readfiles/pages-vs-site-pages.md
View file

This file was deleted.

35 changes: 18 additions & 17 deletions content/en/variables/page.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ The following is a list of page-level variables. Many of these will be defined i
: Aliases of this page

.Ancestors
: Get the ancestors of each page, simplify [breadcrumb navigation](/content-management/sections#example-breadcrumb-navigation) implementation complexity
: Ancestors of this page.

.BundleType
: The [bundle] type: `leaf`, `branch`, or an empty string if the page is not a bundle.
Expand Down Expand Up @@ -85,17 +85,14 @@ The following is a list of page-level variables. Many of these will be defined i
: Access when creating links to the content. If set, Hugo will use the `linktitle` from the front matter before `title`.

.Next
: Points up to the next [regular page](/variables/site/#site-pages) (sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath)). Example: `{{ with .Next }}{{ .Permalink }}{{ end }}`. Calling `.Next` from the first page returns `nil`.
: Points up to the next regular page (sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath)). Example: `{{ with .Next }}{{ .Permalink }}{{ end }}`. Calling `.Next` from the first page returns `nil`.

.NextInSection
: Points up to the next [regular page](/variables/site/#site-pages) below the same top level section (e.g. in `/blog`)). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath). Example: `{{ with .NextInSection }}{{ .Permalink }}{{ end }}`. Calling `.NextInSection` from the first page returns `nil`.
: Points up to the next regular page below the same top level section (e.g. in `/blog`)). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath). Example: `{{ with .NextInSection }}{{ .Permalink }}{{ end }}`. Calling `.NextInSection` from the first page returns `nil`.

.OutputFormats
: Contains all formats, including the current format, for a given page. Can be combined the with [`.Get` function](/functions/get/) to grab a specific format. (See [Output Formats](/templates/output-formats/).)

.Pages
: A collection of associated pages. This value will be `nil` within the context of regular content pages. See [`.Pages`](#pages).

.Permalink
: The Permanent link for this page; see [Permalinks](/content-management/urls/)

Expand All @@ -106,10 +103,10 @@ The following is a list of page-level variables. Many of these will be defined i
: The slice of strings that results from splitting .Plain into words, as defined in Go's [strings.Fields](https://pkg.go.dev/strings#Fields).

.Prev
: Points down to the previous [regular page](/variables/site/#site-pages) (sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath)). Example: `{{ if .Prev }}{{ .Prev.Permalink }}{{ end }}`. Calling `.Prev` from the last page returns `nil`.
: Points down to the previous regular page(sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath)). Example: `{{ if .Prev }}{{ .Prev.Permalink }}{{ end }}`. Calling `.Prev` from the last page returns `nil`.

.PrevInSection
: Points down to the previous [regular page](/variables/site/#site-pages) below the same top level section (e.g. `/blog`). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath). Example: `{{ if .PrevInSection }}{{ .PrevInSection.Permalink }}{{ end }}`. Calling `.PrevInSection` from the last page returns `nil`.
: Points down to the previous regular page below the same top level section (e.g. `/blog`). Pages are sorted by Hugo's [default sort](/templates/lists#default-weight--date--linktitle--filepath). Example: `{{ if .PrevInSection }}{{ .PrevInSection.Permalink }}{{ end }}`. Calling `.PrevInSection` from the last page returns `nil`.

.PublishDate
: The date on which the content was or will be published. By default, this is the front matter `publishDate` value. See [configuring dates] for a description of fallback values and precedence. See also `.Date`, `.ExpiryDate`, and `.Lastmod`.
Expand Down Expand Up @@ -173,6 +170,19 @@ https://remarkjs.com)
.WordCount
: The number of words in the content.

## Page collections

List pages receive the following page collections in [context](/getting-started/glossary/#context):

.Pages
: Regular pages within the current section (not recursive), and section pages for immediate descendant sections (not recursive).

.RegularPages
: Regular pages within the current section (not recursive).

.RegularPagesRecursive
: Regular pages within the current section, and regular pages within all descendant sections.

## Writable page-scoped variables

[.Scratch][scratch]
Expand All @@ -187,15 +197,6 @@ Also see [Sections](/content-management/sections/).

{{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}}

## The `.Pages` variable {#pages}

`.Pages` is an alias to `.Data.Pages`. It is conventional to use the
aliased form `.Pages`.

### `.Pages` compared to `.Site.Pages`

{{< getcontent path="readfiles/pages-vs-site-pages.md" >}}

## Page fragments

{{< new-in "0.111.0" >}}
Expand Down
Loading

0 comments on commit a51bf9f

Please sign in to comment.