github.com/rabbouni145/gg@v0.47.1/docs/content/en/about/new-in-032/index.md (about)

     1  ---
     2  title: Hugo 0.32 HOWTO
     3  description: About page bundles, image processing and more.
     4  date: 2017-12-28
     5  keywords: [ssg,static,performance,security]
     6  menu:
     7    docs:
     8      parent: "about"
     9      weight: 10
    10  weight: 10
    11  sections_weight: 10
    12  draft: false
    13  aliases: []
    14  toc: true
    15  images:
    16  - images/blog/sunset.jpg
    17  ---
    18  
    19  
    20  {{% note %}}
    21  This documentation belongs in other places in this documentation site, but is put here first ... to get something up and running fast.
    22  {{% /note %}}
    23  
    24  
    25  Also see this demo project from [bep](https://github.com/bep/), the clever Norwegian behind these new features:
    26  
    27  * https://temp.bep.is/hugotest/
    28  * https://github.com/bep/hugotest (source)
    29  
    30  ## Page Resources
    31  
    32  ### Organize Your Content
    33  
    34  {{< figure src="/images/hugo-content-bundles.png" title="Pages with image resources" >}}
    35  
    36  The content folder above shows a mix of content pages (`md` (i.e. markdown) files) and image resources.
    37  
    38  {{% note %}}
    39  You can use any file type as a content resource as long as it is a MIME type recognized by Hugo (`json` files will, as one example, work fine). If you want to get exotic, you can define your [own media type](/templates/output-formats/#media-types).
    40  {{% /note %}}
    41  
    42  The 3 page bundles marked in red explained from top to bottom:
    43  
    44  1. The home page with one image resource (`1-logo.png`)
    45  2. The blog section with two images resources and two pages resources (`content1.md`, `content2.md`). Note that the `_index.md` represents the URL for this section.
    46  3. An article (`hugo-is-cool`) with a folder with some images and one content resource (`cats-info.md`). Note that the `index.md` represents the URL for this article.
    47  
    48  The content files below `blog/posts` are just regular standalone pages.
    49  
    50  {{% note %}}
    51  Note that changes to any resource inside the `content` folder will trigger a reload when running in watch (aka server or live reload mode), it will even work with `--navigateToChanged`.
    52  {{% /note %}}
    53  
    54  #### Sort Order
    55  
    56  * Pages are sorted according to standard Hugo page sorting rules.
    57  * Images and other resources are sorted in lexicographical order.
    58  
    59  ### Handle Page Resources in Templates
    60  
    61  
    62  #### List all Resources
    63  
    64  ```go-html-template
    65  {{ range .Resources }}
    66  <li><a href="{{ .RelPermalink }}">{{ .ResourceType | title }}</a></li>
    67  {{ end }}
    68  ```
    69  
    70  For an absolute URL, use `.Permalink`.
    71  
    72  **Note:** The permalink will be relative to the content page, respecting permalink settings. Also, included page resources will not have a value for `RelPermalink`.
    73  
    74  #### List All Resources by Type
    75  
    76  ```go-html-template
    77  {{ with .Resources.ByType "image" }}
    78  {{ end }}
    79  
    80  ```
    81  
    82  Type here is `page` for pages, else the main type in the MIME type, so `image`, `json` etc.
    83  
    84  #### Get a Specific Resource
    85  
    86  ```go-html-template
    87  {{ $logo := .Resources.GetByPrefix "logo" }}
    88  {{ with $logo }}
    89  {{ end }}
    90  ```
    91  
    92  #### Include Page Resource Content
    93  
    94  ```go-html-template
    95  {{ with .Resources.ByType "page" }}
    96  {{ range . }}
    97  <h3>{{ .Title }}</h3>
    98  {{ .Content }}
    99  {{ end }}
   100  {{ end }}
   101  
   102  ```
   103  
   104  
   105  ## Image Processing
   106  
   107  The `image` resource implements the methods `Resize`, `Fit` and `Fill`:
   108  
   109  Resize
   110  : Resize to the given dimension, `{{ $logo.Resize "200x" }}` will resize to 200 pixels wide and preserve the aspect ratio. Use `{{ $logo.Resize "200x100" }}` to control both height and width.
   111  
   112  Fit
   113  : Scale down the image to fit the given dimensions, e.g. `{{ $logo.Fit "200x100" }}` will fit the image inside a box that is 200 pixels wide and 100 pixels high.
   114  
   115  Fill
   116  : Resize and crop the image given dimensions, e.g. `{{ $logo.Fill "200x100" }}` will resize and crop to width 200 and height 100
   117  
   118  
   119  {{% note %}}
   120  Image operations in Hugo currently **do not preserve EXIF data** as this is not supported by Go's [image package](https://github.com/golang/go/search?q=exif&type=Issues&utf8=%E2%9C%93). This will be improved on in the future.
   121  {{% /note %}}
   122  
   123  
   124  ### Image Processing Examples
   125  
   126  _The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_
   127  
   128  
   129  {{< imgproc sunset Resize "300x" />}}
   130  
   131  {{< imgproc sunset Fill "90x120 left" />}}
   132  
   133  {{< imgproc sunset Fill "90x120 right" />}}
   134  
   135  {{< imgproc sunset Fit "90x90" />}}
   136  
   137  {{< imgproc sunset Resize "300x q10" />}}
   138  
   139  
   140  This is the shortcode used in the examples above:
   141  
   142  
   143  {{< code file="layouts/shortcodes/imgproc.html" >}}
   144  {{< readfile file="layouts/shortcodes/imgproc.html" >}}   
   145  {{< /code >}}
   146  
   147  And it is used like this:
   148  
   149  ```go-html-template
   150  {{</* imgproc sunset Resize "300x" */>}}
   151  ```
   152  
   153  ### Image Processing Options
   154  
   155  In addition to the dimensions (e.g. `200x100`) where either height or width can be omitted, Hugo supports a set of additional image options:
   156  
   157  Anchor
   158  : Only relevant for `Fill`. This is useful for thumbnail generation where the main motive is located in, say, the left corner. Valid are `Center`, `TopLeft`, `Top`, `TopRight`, `Left`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`. Example: `{{ $logo.Fill "200x100 BottomLeft" }}`
   159  
   160  JPEG Quality
   161  : Only relevant for JPEG images, values 1 to 100 inclusive, higher is better. Default is 75. `{{ $logo.Resize "200x q50" }}`
   162  
   163  Rotate
   164  : Rotates an image by the given angle counter-clockwise. The rotation will be performed first to get the dimensions correct. `{{ $logo.Resize "200x r90" }}`. The main use of this is to be able to manually correct for [EXIF orientation](https://github.com/golang/go/issues/4341) of JPEG images.
   165  
   166  Resample Filter
   167  : Filter used in resizing. Default is `Box`, a simple and fast resampling filter appropriate for downscaling. See https://github.com/disintegration/imaging for more. If you want to trade quality for faster processing, this may be a option to test. 
   168  
   169  
   170  
   171  ### Performance
   172  
   173  Processed images are stored below `<project-dir>/resources` (can be set with `resourceDir` config setting). This folder is deliberately placed in the project, as it is recommended to check these into source control as part of the project. These images are not "Hugo fast" to generate, but once generated they can be reused.
   174  
   175  If you change your image settings (e.g. size), remove or rename images etc., you will end up with unused images taking up space and cluttering your project. 
   176  
   177  To clean up, run:
   178  
   179  ```bash
   180  hugo --gc
   181  ```
   182  
   183  
   184  {{% note %}}
   185  **GC** is short for **Garbage Collection**.
   186  {{% /note %}}
   187  
   188  
   189  ## Configuration
   190  
   191  ### Default Image Processing Config
   192  
   193  You can configure an `imaging` section in `config.toml` with default image processing options:
   194  
   195  ```toml
   196  [imaging]
   197  # Default resample filter used for resizing. Default is Box,
   198  # a simple and fast averaging filter appropriate for downscaling.
   199  # See https://github.com/disintegration/imaging
   200  resampleFilter = "box"
   201  
   202  # Defatult JPEG quality setting. Default is 75.
   203  quality = 68
   204  ```
   205  
   206  
   207  
   208  
   209