mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
a6e635ca7d
fcc3ed651 Remove some expired new-in a9c5981f5 Fix cascade example 82bb250fa Add some lines about permalinks tokens in front matter 328fe564e Remove some outdated new-in fb140b153 Hide showcase menu entry 42d9d1c79 Update image formats from which EXIF data can be extracted 09ad56b6e netlify: Hugo 0.130.0 1d503f846 Merge branch 'tempv0.130.0' e2458074d math: Add trigonometric functions and some angle helper functions 392afc8f9 Disable the showcase section for now 0300750f2 Improve example of image render hook 60a9306af Improve description of the .Site.RegularPages method 8d759175d Fix typos 55daa4554 Update XxHash.md 397c81cb7 Add namespace for hash functions 70fe8d2f0 netlify: Bump Hugo 0.129.0 5a9771aff Merge branch 'tempv0.129.0' f9146575b Fix typo e6e1fea49 Fix typo in Hugo docs | functions | partial 732d10ec4 source: Expose GitInfo Body 34c97e639 netlify: Hugo 0.128.2 3270587e9 Fix typo 727c5396e netlify: Hugo 0.128.1 80b6ae99c Update GitHub Pages workflow file example 027134102 Update GitHub Pages workflow file example 2600a8a2e Miscellaneous edits 3fdd5819b Update Build.md 7764005c3 Improve example of render hook directory structure 5e3941d82 Fix typos 748bf065f Restructure templates section fafbf6566 Update Defer.md 012162e0d Document changes to template functions in v0.128.0 0990ce35b quick-reference: Update emojis 6677a30ef Update Goldmark configuration documentation 4449d530d Document new pagination config 0af8be439 Update Defer.md 56348196d netlify: Hugo 0.128.0 d67b6d82e Update content/en/functions/templates/Defer.md 23d996b3d Update content/en/functions/templates/Defer.md 7f7fb2f27 Document templates.Defer 5ada1e9d5 Fix docs merge (remove shortcode) d27ee6156 Merge branch 'tempv0.128.0' 5d7317c84 Fix typo 7c18ee546 Update theme 83bfea63b Update theme b274b3238 Merge commit '8b9803425e63e1b1801f8d5d676e96368d706722' ff34a035a deploy: Add stripIndexHtml target option d9e964bdb markup/goldmark: Add the Hugo Goldmark Extras "delete" extension ac5bd16d2 deps: Upgrade github.com/alecthomas/chroma v2.13.0 => v2.14.0 25377171b config: Remove extraneous BuildConfig setting 0d2044f6d docs: Regen docshelper a2548dac9 markup/goldmark: Support extras extension 9d0c86ee8 commands: Add gen chromastyles --lineNumbersTableStyle flag git-subtree-dir: docs git-subtree-split: fcc3ed651a1b6431303c2f88f20fa38531c52b3d
161 lines
6.6 KiB
Markdown
161 lines
6.6 KiB
Markdown
---
|
|
title: Page bundles
|
|
description: Use page bundles to logically associate one or more resources with content.
|
|
categories: [content management]
|
|
keywords: [page,bundle,leaf,branch]
|
|
menu :
|
|
docs:
|
|
parent: content-management
|
|
weight: 30
|
|
weight: 30
|
|
toc: true
|
|
---
|
|
|
|
## Introduction
|
|
|
|
A page bundle is a directory that encapsulates both content and associated resources.
|
|
|
|
By way of example, this site has an "about" page and a "privacy" page:
|
|
|
|
```text
|
|
content/
|
|
├── about/
|
|
│ ├── index.md
|
|
│ └── welcome.jpg
|
|
└── privacy.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.
|
|
|
|
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` |
|
|
| Template types | [single] | [home], [section], [taxonomy], or [term] |
|
|
| 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` |
|
|
|
|
[single]: /templates/types/#single
|
|
[home]: /templates/types/#home
|
|
[section]: /templates/types/#section
|
|
[taxonomy]: /templates/types/#taxonomy
|
|
[term]: /templates/types/#term
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
```text
|
|
content/
|
|
├── about
|
|
│ └── index.md
|
|
├── posts
|
|
│ ├── my-post
|
|
│ │ ├── content-1.md
|
|
│ │ ├── content-2.md
|
|
│ │ ├── image-1.jpg
|
|
│ │ ├── image-2.png
|
|
│ │ └── index.md
|
|
│ └── my-other-post
|
|
│ └── index.md
|
|
└── another-section
|
|
├── foo.md
|
|
└── not-a-leaf-bundle
|
|
├── bar.md
|
|
└── another-leaf-bundle
|
|
└── index.md
|
|
```
|
|
|
|
There are four leaf bundles in the example above:
|
|
|
|
about
|
|
: This leaf bundle does not contain any page resources.
|
|
|
|
my-post
|
|
: This leaf bundle contains an index file, two resources of [resource type] `page`, and two resources of resource type `image`.
|
|
|
|
- content-1, content-2
|
|
|
|
These are resources of resource type `page`, accessible via the [`Resources`] method on the `Page` object. Hugo will not render these as individual pages.
|
|
|
|
- image-1, image-2
|
|
|
|
These are resources of resource type `image`, accessible via the `Resources` method on the `Page` object
|
|
|
|
my-other-post
|
|
: This leaf bundle does not contain any page resources.
|
|
|
|
another-leaf-bundle
|
|
: This leaf bundle does not contain any page resources.
|
|
|
|
{{% note %}}
|
|
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.
|
|
{{% /note %}}
|
|
|
|
## Branch bundles
|
|
|
|
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.
|
|
|
|
```text
|
|
content/
|
|
├── branch-bundle-1/
|
|
│ ├── _index.md
|
|
│ ├── content-1.md
|
|
│ ├── content-2.md
|
|
│ ├── image-1.jpg
|
|
│ └── image-2.png
|
|
├── branch-bundle-2/
|
|
│ ├── a-leaf-bundle/
|
|
│ │ └── index.md
|
|
│ └── _index.md
|
|
└── _index.md
|
|
```
|
|
|
|
There are three branch bundles in the example above:
|
|
|
|
home page
|
|
: This branch bundle contains an index file, two descendant branch bundles, and no resources.
|
|
|
|
branch-bundle-1
|
|
: This branch bundle contains an index file, two resources of [resource type] `page`, and two resources of resource type `image`.
|
|
|
|
branch-bundle-2
|
|
: This branch bundle contains an index file and a leaf bundle.
|
|
|
|
{{% note %}}
|
|
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.
|
|
{{% /note %}}
|
|
|
|
|
|
## 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/
|
|
[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
|