mirror of
https://github.com/gohugoio/hugoDocs.git
synced 2025-09-15 17:24:49 -04:00
Revise page bundle descriptions
This commit is contained in:
Joe Mooring
GitHub
parent
021eea7b1d
commit
34f099e1ea
@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: Page bundles
|
title: Page bundles
|
||||||
description: Content organization using Page Bundles
|
description: Use page bundles to logically associate one or more resources with content.
|
||||||
categories: [content management]
|
categories: [content management]
|
||||||
keywords: [page,bundle,leaf,branch]
|
keywords: [page,bundle,leaf,branch]
|
||||||
menu :
|
menu :
|
||||||
@ -11,173 +11,147 @@ weight: 30
|
|||||||
toc: true
|
toc: true
|
||||||
---
|
---
|
||||||
|
|
||||||
Page Bundles are a way to group [Page Resources](/content-management/page-resources/).
|
## Introduction
|
||||||
|
|
||||||
A Page Bundle can be one of:
|
A page bundle is a directory that encapsulates both content and associated resources.
|
||||||
|
|
||||||
- Leaf Bundle (leaf means it has no children)
|
By way of example, this site has an "about" page and a "privacy" page:
|
||||||
- Branch Bundle (home page, section, taxonomy terms, taxonomy list)
|
|
||||||
|
|
||||||
| | Leaf Bundle | Branch Bundle |
|
```text
|
||||||
|-------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------|
|
content/
|
||||||
| Usage | Collection of content and attachments for single pages | Collection of attachments for section pages (home page, section, taxonomy terms, taxonomy list) |
|
├── about/
|
||||||
| Index file name | `index.md` [^fn:1] | `_index.md` [^fn:1] |
|
│ ├── index.md
|
||||||
| Allowed Resources | Page and non-page (like images, PDF, etc.) types | Only non-page (like images, PDF, etc.) types |
|
│ └── welcome.jpg
|
||||||
| Where can the Resources live? | At any directory level within the leaf bundle directory. | At any directory level within the branch bundle directory. |
|
└── privacy.md
|
||||||
| Layout type | [`single`](/templates/single-page-templates/) | [`list`](/templates/lists) |
|
```
|
||||||
| Nesting | Does not allow nesting of more bundles under it | Allows nesting of leaf or branch bundles under it |
|
|
||||||
| Example | `content/posts/my-post/index.md` | `content/posts/_index.md` |
|
The "about" page is a page bundle. It logically associates a resource with content by bundling them together. Resources within a page bundle are [page resources], accessible with the [`Resources`] method on the `Page` object.
|
||||||
| Content from non-index page files...| Accessed only as page resources | Accessed only as regular pages |
|
|
||||||
|
Page bundles are either _leaf bundles_ or _branch bundles_.
|
||||||
|
|
||||||
|
leaf bundle
|
||||||
|
: A _leaf bundle_ is a directory that contains an index.md file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
|
||||||
|
|
||||||
|
branch bundle
|
||||||
|
: A _branch bundle_ is a directory that contains an _index.md file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without _index.md files are also branch bundles. This includes the home page.
|
||||||
|
|
||||||
|
{{% note %}}
|
||||||
|
In the definitions above and the examples below, the extension of the index file depends on the [content format]. For example, use index.md for Markdown content, index.html for HTML content, index.adoc for AsciiDoc content, etc.
|
||||||
|
|
||||||
|
[content format]: /getting-started/glossary/#content-format
|
||||||
|
{{% /note %}}
|
||||||
|
|
||||||
|
## Comparison
|
||||||
|
|
||||||
|
Page bundle characteristics vary by bundle type.
|
||||||
|
|
||||||
|
| | Leaf bundle | Branch bundle |
|
||||||
|
|---------------------|---------------------------------------------------------|---------------------------------------------------------|
|
||||||
|
| Index file | index.md | _index.md |
|
||||||
|
| Example | content/about/index.md | content/posts/_index.md |
|
||||||
|
| [Page kinds] | `page` | `home`, `section`, `taxonomy`, or `term` |
|
||||||
|
| Layout type | [single] | [list] |
|
||||||
|
| Descendant pages | None | Zero or more |
|
||||||
|
| Resource location | Adjacent to the index file or in a nested subdirectory | Same as a leaf bundles, but excludes descendant bundles |
|
||||||
|
| [Resource types] | `page`, `image`, `video`, etc. | all but `page` |
|
||||||
|
|
||||||
|
Files with [resource type] `page` include content written in Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode. In a leaf bundle, excluding the index file, these files are only accessible as page resources. In a branch bundle, these files are only accessible as content pages.
|
||||||
|
|
||||||
## Leaf bundles
|
## Leaf bundles
|
||||||
|
|
||||||
A _Leaf Bundle_ is a directory at any hierarchy within the `content/`
|
A _leaf bundle_ directory that contains an index.md file and zero or more resources. Analogous to a physical leaf, a leaf bundle is at the end of a branch. It has no descendants.
|
||||||
directory, that contains an **`index.md`** file.
|
|
||||||
|
|
||||||
### Examples of leaf bundle organization {#examples-of-leaf-bundle-organization}
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
content/
|
content/
|
||||||
├── about
|
├── about
|
||||||
│ ├── index.md
|
│ └── index.md
|
||||||
├── posts
|
├── posts
|
||||||
│ ├── my-post
|
│ ├── my-post
|
||||||
│ │ ├── content1.md
|
│ │ ├── content-1.md
|
||||||
│ │ ├── content2.md
|
│ │ ├── content-2.md
|
||||||
│ │ ├── image1.jpg
|
│ │ ├── image-1.jpg
|
||||||
│ │ ├── image2.png
|
│ │ ├── image-2.png
|
||||||
│ │ └── index.md
|
│ │ └── index.md
|
||||||
│ └── my-other-post
|
│ └── my-other-post
|
||||||
│ └── index.md
|
│ └── index.md
|
||||||
│
|
|
||||||
└── another-section
|
└── another-section
|
||||||
├── ..
|
├── foo.md
|
||||||
└── not-a-leaf-bundle
|
└── not-a-leaf-bundle
|
||||||
├── ..
|
├── bar.md
|
||||||
└── another-leaf-bundle
|
└── another-leaf-bundle
|
||||||
└── index.md
|
└── index.md
|
||||||
```
|
```
|
||||||
|
|
||||||
In the above example `content/` directory, there are four leaf
|
There are four leaf bundles in the example above:
|
||||||
bundles:
|
|
||||||
|
|
||||||
about
|
about
|
||||||
: This leaf bundle is at the root level (directly under
|
: This leaf bundle does not contain any page resources.
|
||||||
`content` directory) and has only the `index.md`.
|
|
||||||
|
|
||||||
my-post
|
my-post
|
||||||
: This leaf bundle has the `index.md`, two other content
|
: This leaf bundle contains an index file, two resources of [resource type] `page`, and two resources of resource type `image`.
|
||||||
Markdown files and two image files.
|
|
||||||
|
|
||||||
- image1, image2:
|
- content-1, content-2
|
||||||
These images are page resources of `my-post`
|
|
||||||
and only available in `my-post/index.md` resources.
|
|
||||||
|
|
||||||
- content1, content2:
|
These are resources of resource type `page`, accessible via the [`Resources`] method on the `Page` object. Hugo will not render these as individual pages.
|
||||||
These content files are page resources of `my-post`
|
|
||||||
and only available in `my-post/index.md` resources.
|
- image-1, image-2
|
||||||
They will **not** be rendered as individual pages.
|
|
||||||
|
These are resources of resource type `image`, accessible via the `Resources` method on the `Page` object
|
||||||
|
|
||||||
my-other-post
|
my-other-post
|
||||||
: This leaf bundle has only the `index.md`.
|
: This leaf bundle does not contain any page resources.
|
||||||
|
|
||||||
another-leaf-bundle
|
another-leaf-bundle
|
||||||
: This leaf bundle is nested under couple of
|
: This leaf bundle does not contain any page resources.
|
||||||
directories. This bundle also has only the `index.md`.
|
|
||||||
|
|
||||||
{{% note %}}
|
{{% note %}}
|
||||||
The hierarchy depth at which a leaf bundle is created does not matter,
|
Create leaf bundles at any depth within the content directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants.
|
||||||
as long as it is not inside another **leaf** bundle.
|
|
||||||
{{% /note %}}
|
{{% /note %}}
|
||||||
|
|
||||||
### Headless bundle
|
|
||||||
|
|
||||||
A headless bundle is a bundle that is configured to not get published
|
|
||||||
anywhere:
|
|
||||||
|
|
||||||
- It will have no `Permalink` and no rendered HTML in `public/`.
|
|
||||||
- It will not be part of `.Site.RegularPages`, etc.
|
|
||||||
|
|
||||||
But you can get it by `.Site.GetPage`. Here is an example:
|
|
||||||
|
|
||||||
```go-html-template
|
|
||||||
{{ $headless := .Site.GetPage "/some-headless-bundle" }}
|
|
||||||
{{ $reusablePages := $headless.Resources.Match "author*" }}
|
|
||||||
<h2>Authors</h2>
|
|
||||||
{{ range $reusablePages }}
|
|
||||||
<h3>{{ .Title }}</h3>
|
|
||||||
{{ .Content }}
|
|
||||||
{{ end }}
|
|
||||||
```
|
|
||||||
|
|
||||||
_In this example, we are assuming the `some-headless-bundle` to be a headless
|
|
||||||
bundle containing one or more **page** resources whose `.Name` matches
|
|
||||||
`"author*"`._
|
|
||||||
|
|
||||||
Explanation of the above example:
|
|
||||||
|
|
||||||
1. Get the `some-headless-bundle` Page "object".
|
|
||||||
2. Collect a _slice_ of resources in this _Page Bundle_ that matches
|
|
||||||
`"author*"` using `.Resources.Match`.
|
|
||||||
3. Loop through that _slice_ of nested pages, and output their `.Title` and
|
|
||||||
`.Content`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
A leaf bundle can be made headless by adding below in the front matter
|
|
||||||
(in the `index.md`):
|
|
||||||
|
|
||||||
{{< code-toggle file=content/headless/index.md fm=true >}}
|
|
||||||
headless = true
|
|
||||||
{{< /code-toggle >}}
|
|
||||||
|
|
||||||
There are many use cases of such headless page bundles:
|
|
||||||
|
|
||||||
- Shared media galleries
|
|
||||||
- Reusable page content "snippets"
|
|
||||||
|
|
||||||
## Branch bundles
|
## Branch bundles
|
||||||
|
|
||||||
A _Branch Bundle_ is any directory at any hierarchy within the
|
A _branch bundle_ is a directory that contains an _index.md file and zero or more resources. Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without _index.md files are also branch bundles. This includes the home page.
|
||||||
`content/` directory, that contains at least an **`_index.md`** file.
|
|
||||||
|
|
||||||
This `_index.md` can also be directly under the `content/` directory.
|
|
||||||
|
|
||||||
{{% note %}}
|
|
||||||
Here `md` (Markdown) is used just as an example. You can use any file
|
|
||||||
type as a content resource as long as it is a content type recognized by Hugo.
|
|
||||||
{{% /note %}}
|
|
||||||
|
|
||||||
### Examples of branch bundle organization
|
|
||||||
|
|
||||||
```text
|
```text
|
||||||
content/
|
content/
|
||||||
├── branch-bundle-1
|
├── branch-bundle-1/
|
||||||
│ ├── branch-content1.md
|
│ ├── _index.md
|
||||||
│ ├── branch-content2.md
|
│ ├── content-1.md
|
||||||
│ ├── image1.jpg
|
│ ├── content-2.md
|
||||||
│ ├── image2.png
|
│ ├── image-1.md
|
||||||
|
│ └── image-2.md
|
||||||
|
├── branch-bundle-2/
|
||||||
|
│ ├── a-leaf-bundle/
|
||||||
|
│ │ └── index.md
|
||||||
│ └── _index.md
|
│ └── _index.md
|
||||||
└── branch-bundle-2
|
└── _index.md
|
||||||
├── _index.md
|
|
||||||
└── a-leaf-bundle
|
|
||||||
└── index.md
|
|
||||||
```
|
```
|
||||||
|
|
||||||
In the above example `content/` directory, there are two branch
|
There are three branch bundles in the example above:
|
||||||
bundles (and a leaf bundle):
|
|
||||||
|
home page
|
||||||
|
: This branch bundle contains an index file, two descendant branch bundles, and no resources.
|
||||||
|
|
||||||
branch-bundle-1
|
branch-bundle-1
|
||||||
: This branch bundle has the `_index.md`, two
|
: This branch bundle contains an index file, two resources of [resource type] `page`, and two resources of resource type `image`.
|
||||||
other content Markdown files and two image files.
|
|
||||||
|
|
||||||
branch-bundle-2
|
branch-bundle-2
|
||||||
: This branch bundle has the `_index.md` and a
|
: This branch bundle contains an index file and a leaf bundle.
|
||||||
nested leaf bundle.
|
|
||||||
|
|
||||||
{{% note %}}
|
{{% note %}}
|
||||||
The hierarchy depth at which a branch bundle is created does not
|
Create branch bundles at any depth within the content directory, but a leaf bundle may not contain another bundle. Leaf bundles do not have descendants.
|
||||||
matter.
|
|
||||||
{{% /note %}}
|
{{% /note %}}
|
||||||
|
|
||||||
[^fn:1]: The `.md` extension is just an example. The extension can be `.html`, `.json` or any valid MIME type.
|
|
||||||
|
## Headless bundles
|
||||||
|
|
||||||
|
Use [build options] in front matter to create an unpublished leaf or branch bundle whose content and resources you can include in other pages.
|
||||||
|
|
||||||
|
[`Resources`]: /methods/page/resources/
|
||||||
|
[build options]: content-management/build-options/
|
||||||
|
[list]: /templates/lists/
|
||||||
|
[page kinds]: /getting-started/glossary/#page-kind
|
||||||
|
[page resources]: /content-management/page-resources/
|
||||||
|
[resource type]: /getting-started/glossary/#resource-type
|
||||||
|
[resource types]: /getting-started/glossary/#resource-type
|
||||||
|
[single]: /templates/single-page-templates/
|
||||||
|
|||||||
@ -18,6 +18,7 @@ weight: 60
|
|||||||
[E](#environment)
|
[E](#environment)
|
||||||
[F](#field)
|
[F](#field)
|
||||||
[G](#global-resource)
|
[G](#global-resource)
|
||||||
|
[H](#headless-bundle)
|
||||||
[I](#identifier)
|
[I](#identifier)
|
||||||
[K](#kind)
|
[K](#kind)
|
||||||
[L](#layout)
|
[L](#layout)
|
||||||
@ -58,7 +59,7 @@ A data type with two possible values, either `true` or `false`.
|
|||||||
|
|
||||||
###### branch bundle
|
###### 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 directory that contains an _index.md file and zero or more [resources](#resource). Analogous to a physical branch, a branch bundle may have descendants including leaf bundles and other branch bundles. Top level directories with or without _index.md files are also branch bundles. This includes the home page. See [details](/content-management/page-bundles/).
|
||||||
|
|
||||||
###### build
|
###### build
|
||||||
|
|
||||||
@ -156,6 +157,10 @@ A file within the assets directory, or within any directory [mounted](/hugo-modu
|
|||||||
[`resources.Match`]: /functions/resources/match/
|
[`resources.Match`]: /functions/resources/match/
|
||||||
[`resources.ByType`]: /functions/resources/byType/
|
[`resources.ByType`]: /functions/resources/byType/
|
||||||
|
|
||||||
|
###### headless bundle
|
||||||
|
|
||||||
|
An unpublished leaf or branch bundle whose content and resources you can include in other pages. See [build options](/content-management/build-options/).
|
||||||
|
|
||||||
###### identifier
|
###### identifier
|
||||||
|
|
||||||
A string that represents a variable, method, object, or field. It must conform to Go's [language specification](https://go.dev/ref/spec#Identifiers), beginning with a letter or underscore, followed by zero or more letters, digits, or underscores.
|
A string that represents a variable, method, object, or field. It must conform to Go's [language specification](https://go.dev/ref/spec#Identifiers), beginning with a letter or underscore, followed by zero or more letters, digits, or underscores.
|
||||||
@ -192,7 +197,7 @@ See [template](#template).
|
|||||||
|
|
||||||
###### leaf bundle
|
###### leaf bundle
|
||||||
|
|
||||||
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/).
|
A directory that contains 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. It has no descendants. See [details](/content-management/page-bundles/).
|
||||||
|
|
||||||
###### list page
|
###### list page
|
||||||
|
|
||||||
@ -331,6 +336,13 @@ Any file consumed by the build process to augment or generate content, structure
|
|||||||
|
|
||||||
Hugo supports three types of resources: [global](#global-resource), [page](#page-resource), and [remote](#remote-resource)
|
Hugo supports three types of resources: [global](#global-resource), [page](#page-resource), and [remote](#remote-resource)
|
||||||
|
|
||||||
|
###### resource type
|
||||||
|
|
||||||
|
The main type of a resource's [media type]. Content files such as Markdown, HTML, AsciiDoc, Pandoc, reStructuredText, and Emacs Org Mode have resource type `page`. Other resource types include `image`, `video`, etc. Retrieve the resource type using the [`ResourceType`] method on a `Resource` object.
|
||||||
|
|
||||||
|
[media type]: /methods/resource/mediatype/
|
||||||
|
[`ResourceType`]: /methods/resource/resourcetype/
|
||||||
|
|
||||||
###### scalar
|
###### scalar
|
||||||
|
|
||||||
A single value, one of [string](#string), [integer](#integer), [floating point](#floating-point), or [boolean](#boolean).
|
A single value, one of [string](#string), [integer](#integer), [floating point](#floating-point), or [boolean](#boolean).
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user