diff options
author | Ivan Boothe <git@rootwork.org> | 2022-04-07 04:22:41 +0300 |
---|---|---|
committer | Ivan Boothe <git@rootwork.org> | 2022-04-07 04:22:41 +0300 |
commit | b1bf29ad7c3a4ccb85553e98e6abb1c9052330da (patch) | |
tree | 68bd33cb8ca484680b9f7a85d6ad82145dbc04de | |
parent | 18a2b22cf91f1fb8b58b4a28aba5b974fe3011b3 (diff) |
updating bundle example
Signed-off-by: Ivan Boothe <git@rootwork.org>
-rw-r--r-- | exampleSite/content/bundle/building.webp | bin | 0 -> 1210 bytes | |||
-rw-r--r-- | exampleSite/content/bundle/index.md | 27 |
2 files changed, 24 insertions, 3 deletions
diff --git a/exampleSite/content/bundle/building.webp b/exampleSite/content/bundle/building.webp Binary files differnew file mode 100644 index 0000000..49f636b --- /dev/null +++ b/exampleSite/content/bundle/building.webp diff --git a/exampleSite/content/bundle/index.md b/exampleSite/content/bundle/index.md index c9f17fc..1ccd279 100644 --- a/exampleSite/content/bundle/index.md +++ b/exampleSite/content/bundle/index.md @@ -5,6 +5,7 @@ date: '2022-03-24' aliases: - hugo-page-bundles author: 'Hugo Authors' +usePageBundles: true resources: - alt: A building src: building.png @@ -12,7 +13,9 @@ resources: [Page bundles](https://gohugo.io/content-management/page-bundles/) are an optional way to [organize page resources](https://gohugo.io/content-management/page-resources/) within Hugo. -With page bundles, resources for a page or section, like images or attached files, live in the same directory as the content itself rather than in your `static` directory. Page resources in a bundle are only available to the page with which they are bundled, but can be [managed directly from the page's front matter](https://gohugo.io/content-management/page-resources/#page-resources-metadata). +You can opt-in to using page bundles in Hugo Clarity with `usePageBundles` in your site configuration or in a page's front matter. [Read more about `usePageBundles`](https://github.com/chipzoller/hugo-clarity#organizing-page-resources) + +With page bundles, resources for a page or section, like images or attached files, live **in the same directory as the content itself** rather than in your `static` directory. Hugo Clarity supports the use of [leaf bundles](https://gohugo.io/content-management/page-bundles/#leaf-bundles), which are any directories within the `content` directory that contain an `index.md` file. Hugo's documentation gives this example: @@ -46,7 +49,7 @@ bundles: **about**: This leaf bundle is at the root level (directly under `content` directory) and has only the `index.md`. -***my-post***: This leaf bundle has the `index.md`, two other content +**my-post**: This leaf bundle has the `index.md`, two other content Markdown files and two image files. **image1** is a page resource of `my-post` and only available in `my-post/index.md` resources. **image2** is a page resource of `my-post` and only available in `my-post/index.md` resources. @@ -60,6 +63,24 @@ _The hierarchy depth at which a leaf bundle is created does not matter, as long as it is not inside another **leaf** bundle._ </blockquote> -The image below is part of the bundle of this page, and is located at `content/bundle/building.png`. Because it's within this page's bundle, the markup for the image only has to specify the image's filename. +### Advantages to using page bundles + +The image below is part of the bundle of this page, and is located at `content/bundle/building.png`. Because it's within this page's bundle, the markup for the image only has to specify the image's filename, `building.png`. ![A building](building.png) + +If you ever change the name of the directory in which this Markdown file and the image reside, the reference to the image would not need to be updated. + +In addition to more cleanly organizing your content and related assets, when using page bundles, **Hugo Clarity will automatically generate markup for modern image formats**, which are smaller in file size. + +For instance, when you reference an image like `building.png`, Hugo Clarity will check to see if the same image (based on filename) exists in [WebP](https://en.wikipedia.org/wiki/WebP), [AVIF](https://en.wikipedia.org/wiki/AV1#AV1_Image_File_Format_(AVIF)) or [JXL](https://en.wikipedia.org/wiki/JPEG_XL) formats. If you inspect the image above, you'll see a `<source>` element for `building.webp`, because that file is also present. + +Browsers that [support these formats and the `<picture>` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture#the_type_attribute) will load them, while browsers that do not will fall-back to the default image. [Read more about this process.](https://github.com/chipzoller/hugo-clarity#support-for-modern-image-formats) + +Finally, note that page assets can be further managed and refined [within the page's front matter](https://gohugo.io/content-management/page-resources/#page-resources-metadata) if you wish, and are not limited to images alone. + +### Disadvantages to using page bundles + +Page resources in a bundle are only available to the page with which they are bundled — that means you can't include an image with one page and then reference it from another. + +Images that are being used in multiple places are more appropriate for your [Hugo assets directory](https://gohugo.io/hugo-pipes/introduction/). |