github.com/shohhei1126/hugo@v0.42.2-0.20180623210752-3d5928889ad7/docs/content/en/content-management/page-bundles.md (about)

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