hugo

Fork of github.com/gohugoio/hugo with reverse pagination support

git clone git://git.shimmy1996.com/hugo.git

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.