mirror of
https://github.com/gohugoio/hugoDocs.git
synced 2025-09-13 18:27:53 -04:00
Update sections page
This commit is contained in:
Joe Mooring
GitHub
parent
ed35fc6c47
commit
a51bf9f4f6
@ -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:
|
||||
@ -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:
|
||||
|
||||
The sections can be nested as deeply as you need.
|
||||
|
||||
```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
|
||||
```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 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`).**
|
||||
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.
|
||||
|
||||
{{% 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`).
|
||||
## Explanation
|
||||
|
||||
If you need a specific template for a sub-section, you need to adjust either the `type` or `layout` in front matter.
|
||||
{{% /note %}}
|
||||
Sections and non-sections behave differently.
|
||||
|
||||
## Example: breadcrumb navigation
|
||||
||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:
|
||||
|
||||
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:
|
||||
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.
|
||||
|
||||
With the file structure from the [example above](#overview):
|
||||
|
||||
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>
|
||||
@ -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/
|
||||
|
||||
@ -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 _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
|
||||
|
||||
@ -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.
|
||||
@ -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/).
|
||||
@ -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 _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](#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
|
||||
|
||||
@ -212,6 +224,10 @@ A sequence of bytes. For example, `"What is 6 times 7?"` .
|
||||
|
||||
A group of related [terms](#term) used to classify content. For example, a "colors" taxonomy might include the terms "red", "green", and "blue". See [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 [details](/templates/).
|
||||
@ -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 [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).
|
||||
|
||||
@ -1,34 +0,0 @@
|
||||
* A _regular_ page is a "post" page or a "content" page.
|
||||
* A _leaf bundle_ is a regular page.
|
||||
* A _list_ page can list _regular_ pages and other _list_ pages. Some
|
||||
examples are: homepage, section pages, _taxonomy_ (`/tags/`) and
|
||||
_term_ (`/tags/foo/`) pages.
|
||||
* A _branch bundle_ is a _list_ page.
|
||||
|
||||
`.Site.Pages`
|
||||
: Collection of **all** pages of the site: _regular_ pages,
|
||||
sections, taxonomies, etc. -- Superset of everything!
|
||||
|
||||
`.Site.RegularPages`
|
||||
: Collection of only _regular_ pages.
|
||||
|
||||
The above `.Site. ..` page collections can be accessed from any scope in
|
||||
the templates.
|
||||
|
||||
Below variables return a collection of pages only from the scope of
|
||||
the current _list_ page:
|
||||
|
||||
`.Pages`
|
||||
: Collection of _regular_ pages and _only first-level_
|
||||
section pages under the current _list_ page.
|
||||
|
||||
`.RegularPages`
|
||||
: Collection of only _regular_ pages under the
|
||||
current _list_ page. This **excludes** regular pages in nested sections/_list_ pages (those are subdirectories with an `_index.md` file.
|
||||
|
||||
`.RegularPagesRecursive`
|
||||
: Collection of **all** _regular_ pages under a _list_ page. This **includes** regular pages in nested sections/_list_ pages.
|
||||
|
||||
Note
|
||||
: From the scope of _regular_ pages, `.Pages` and
|
||||
`.RegularPages` return an empty slice.
|
||||
@ -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.
|
||||
@ -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/)
|
||||
|
||||
@ -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`.
|
||||
@ -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]
|
||||
@ -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" >}}
|
||||
|
||||
@ -18,7 +18,7 @@ The following is a list of site-level (aka "global") variables. Many of these va
|
||||
|
||||
All the methods below, e.g. `.Site.RegularPages` can also be reached via the global [`site`](/functions/site/) function, e.g. `site.RegularPages`, which can be handy in partials where the `Page` object isn't easily available.
|
||||
|
||||
## Site variables list
|
||||
## Site variables
|
||||
|
||||
.Site.AllPages
|
||||
: array of all pages, regardless of their translation.
|
||||
@ -78,10 +78,10 @@ All the methods below, e.g. `.Site.RegularPages` can also be reached via the glo
|
||||
: all the menus in the site.
|
||||
|
||||
.Site.Pages
|
||||
: array of all content ordered by Date with the newest first. This array contains only the pages in the current language. See [`.Site.Pages`](#site-pages).
|
||||
: array of all content ordered by Date with the newest first. This array contains only the pages in the current language.
|
||||
|
||||
.Site.RegularPages
|
||||
: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`. See [`.Site.Pages`](#site-pages).
|
||||
: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`.
|
||||
|
||||
.Site.Sections
|
||||
: top-level directories of the site.
|
||||
@ -92,7 +92,7 @@ All the methods below, e.g. `.Site.RegularPages` can also be reached via the glo
|
||||
.Site.Title
|
||||
: a string representing the title of the site.
|
||||
|
||||
## The `.Site.Params` variable
|
||||
## Site parameters
|
||||
|
||||
`.Site.Params` is a container holding the values from the `params` section of your site configuration.
|
||||
|
||||
@ -114,10 +114,4 @@ You can use `.Site.Params` in a [partial template](/templates/partials/) to call
|
||||
<meta name="description" content="{{ if .IsHome }}{{ $.Site.Params.description }}{{ else }}{{ .Description }}{{ end }}" />
|
||||
{{< /code >}}
|
||||
|
||||
## The `.Site.Pages` variable {#site-pages}
|
||||
|
||||
### `.Site.Pages` compared to `.Pages`
|
||||
|
||||
{{< getcontent path="readfiles/pages-vs-site-pages.md" >}}
|
||||
|
||||
[config]: /getting-started/configuration/
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user