Images

Treat images as content

• Treat images as content; avoid hard-coding images in templates.
• Refer to images as objects in front matter, using either !g.static (for images contained in the repository), or the path to the object in storage (i.e. Google Cloud Storage in conjunction with the Google Dynamic Image Service extension).

Using these techniques has two primary benefits:

1. Defends against broken images as a build failure will occur if the image is missing.
2. Makes URL changes to the serving URL of your site safe, as the serving URL is dynamically generated by the !g.static tag or the google-cloud-images extension.

image1: !g.static /source/images/foo1.png
image2: /bucket/path/images/foo2.png

image1: /assets/images/foo1.png
image2: /assets/images/foo2.png

Avoid placing images in CSS

Images that are coupled to a piece of content or a partial instance (versus a UI element) should not be implemented using background-image in CSS. Instead, place the image in front matter to benefit from the advantages of treating images as content. As a result, it's easier to maintain these images, and localize them.

<div class="foo">
  <div class="foo__image" style="background-image: url({{partial.image.url}})">
  </div>
</div>

...
image: !g.static /source/images/default.png
image@fr_FR: !g.static /source/images/france.png
image@ja_JP: !g.static /source/images/japan.png

.foo__image
  background:
    repeat: no-repeat
    size: cover
  width: 300px

Use the Google Dynamic Image Service extension

Use the Google Dynamic Image Service extension for image management. Such a system provides many benefits:

• Support for client-side dynamic images. It can:
  • request WebP, JPG, or PNG images depending on browser capabilities,
  • serve images at different compression levels,
  • or resize images depending on breakpoint.
• Minimizes blob storage within the Git repository.

Small files (such as SVGs, icons, or otherwise) may be stored within the Git repository. Projects with fixed sizes (i.e. a small project with just a few images, that will not grow to be a larger project) can continue to store images in Git. Once a project reaches a certain threshold (such as if it has dozens of large images), or has certain performance requirements, images should be moved to a CDN.

ALternatively, a CMS (such as Contentful or Kintaro) may provide its own image-serving solution, which is acceptable to use as it keeps images out of the Git repository.