page-bundles.md (7872B)
1 ---
2 title : "Page Bundles"
3 description : "Content organization using Page Bundles"
4 date : 2018-01-24T13:09:00-05:00
5 linktitle : "Page Bundles"
6 keywords : ["page", "bundle", "leaf", "branch"]
7 categories : ["content management"]
8 toc : true
9 menu :
10 docs:
11 identifier : "page-bundles"
12 parent : "content-management"
13 weight : 11
14 ---
15
16 Page Bundles are a way to group [Page Resources](/content-management/page-resources/).
17
18 A Page Bundle can be one of:
19
20 - Leaf Bundle (leaf means it has no children)
21 - Branch Bundle (home page, section, taxonomy terms, taxonomy list)
22
23 | | Leaf Bundle | Branch Bundle |
24 |-------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
25 | Usage | Collection of content and attachments for single pages | Collection of attachments for section pages (home page, section, taxonomy terms, taxonomy list) |
26 | Index file name | `index.md` [^fn:1] | `_index.md` [^fn:1] |
27 | Allowed Resources | Page and non-page (like images, pdf, etc.) types | Only non-page (like images, pdf, etc.) types |
28 | Where can the Resources live? | At any directory level within the leaf bundle directory. | Only in the directory level **of** the branch bundle directory i.e. the directory containing the `_index.md` ([ref](https://discourse.gohugo.io/t/question-about-content-folder-structure/11822/4?u=kaushalmodi)). |
29 | Layout type | `single` | `list` |
30 | Nesting | Does not allow nesting of more bundles under it | Allows nesting of leaf or branch bundles under it |
31 | Example | `content/posts/my-post/index.md` | `content/posts/_index.md` |
32 | Content from non-index page files... | Accessed only as page resources | Accessed only as regular pages |
33
34
35 ## Leaf Bundles {#leaf-bundles}
36
37 A _Leaf Bundle_ is a directory at any hierarchy within the `content/`
38 directory, that contains an **`index.md`** file.
39
40 ### Examples of Leaf Bundle organization {#examples-of-leaf-bundle-organization}
41
42 ```text
43 content/
44 ├── about
45 │ ├── index.md
46 ├── posts
47 │ ├── my-post
48 │ │ ├── content1.md
49 │ │ ├── content2.md
50 │ │ ├── image1.jpg
51 │ │ ├── image2.png
52 │ │ └── index.md
53 │ └── my-other-post
54 │ └── index.md
55 │
56 └── another-section
57 ├── ..
58 └── not-a-leaf-bundle
59 ├── ..
60 └── another-leaf-bundle
61 └── index.md
62 ```
63
64 In the above example `content/` directory, there are four leaf
65 bundles:
66
67 about
68 : This leaf bundle is at the root level (directly under
69 `content` directory) and has only the `index.md`.
70
71 my-post
72 : This leaf bundle has the `index.md`, two other content
73 Markdown files and two image files.
74
75 image1
76 : This image is a page resource of `my-post`
77 and only available in `my-post/index.md` resources.
78
79 image2
80 : This image is a page resource of `my-post`
81 and only available in `my-post/index.md` resources.
82
83 my-other-post
84 : This leaf bundle has only the `index.md`.
85
86 another-leaf-bundle
87 : This leaf bundle is nested under couple of
88 directories. This bundle also has only the `index.md`.
89
90 {{% note %}}
91 The hierarchy depth at which a leaf bundle is created does not matter,
92 as long as it is not inside another **leaf** bundle.
93 {{% /note %}}
94
95
96 ### Headless Bundle {#headless-bundle}
97
98 A headless bundle is a bundle that is configured to not get published
99 anywhere:
100
101 - It will have no `Permalink` and no rendered HTML in `public/`.
102 - It will not be part of `.Site.RegularPages`, etc.
103
104 But you can get it by `.Site.GetPage`. Here is an example:
105
106 ```go-html-template
107 {{ $headless := .Site.GetPage "/some-headless-bundle" }}
108 {{ $reusablePages := $headless.Resources.Match "author*" }}
109 <h2>Authors</h2>
110 {{ range $reusablePages }}
111 <h3>{{ .Title }}</h3>
112 {{ .Content }}
113 {{ end }}
114 ```
115
116 _In this example, we are assuming the `some-headless-bundle` to be a headless
117 bundle containing one or more **page** resources whose `.Name` matches
118 `"author*"`._
119
120 Explanation of the above example:
121
122 1. Get the `some-headless-bundle` Page "object".
123 2. Collect a *slice* of resources in this *Page Bundle* that matches
124 `"author*"` using `.Resources.Match`.
125 3. Loop through that *slice* of nested pages, and output their `.Title` and
126 `.Content`.
127
128 ---
129
130 A leaf bundle can be made headless by adding below in the Front Matter
131 (in the `index.md`):
132
133 ```toml
134 headless = true
135 ```
136
137 There are many use cases of such headless page bundles:
138
139 - Shared media galleries
140 - Reusable page content "snippets"
141
142
143 ## Branch Bundles {#branch-bundles}
144
145 A _Branch Bundle_ is any directory at any hierarchy within the
146 `content/` directory, that contains at least an **`_index.md`** file.
147
148 This `_index.md` can also be directly under the `content/` directory.
149
150 {{% note %}}
151 Here `md` (markdown) is used just as an example. You can use any file
152 type as a content resource as long as it is a content type recognized by Hugo.
153 {{% /note %}}
154
155
156 ### Examples of Branch Bundle organization {#examples-of-branch-bundle-organization}
157
158 ```text
159 content/
160 ├── branch-bundle-1
161 │ ├── branch-content1.md
162 │ ├── branch-content2.md
163 │ ├── image1.jpg
164 │ ├── image2.png
165 │ └── _index.md
166 └── branch-bundle-2
167 ├── _index.md
168 └── a-leaf-bundle
169 └── index.md
170 ```
171
172 In the above example `content/` directory, there are two branch
173 bundles (and a leaf bundle):
174
175 `branch-bundle-1`
176 : This branch bundle has the `_index.md`, two
177 other content Markdown files and two image files.
178
179 `branch-bundle-2`
180 : This branch bundle has the `_index.md` and a
181 nested leaf bundle.
182
183 {{% note %}}
184 The hierarchy depth at which a branch bundle is created does not
185 matter.
186 {{% /note %}}
187
188 [^fn:1]: The `.md` extension is just an example. The extension can be `.html`, `.json` or any valid MIME type.