Esc

Using theme assets

Because our themes are built to be customized in countless different ways, theme assets serve an important role. Some common examples of theme assets include background images, category and section icons and custom fonts.

In this article

Theme assets are stored within the assets folder in your theme. They can be added directly, by copying files into the assets directory before a theme is imported into Zendesk, or through the Zendesk Guide Theming Center. Once added, they can be used throughout the theme.

Types

The following file types are permitted by Zendesk:

Asset type Permitted file types
Images jpg, jpeg, png, gif, svg, webp, tiff, tif, bmp, ico, webm
Fonts woff2, woff, eot, otf, ttf, svg
Text files js, css, html, json, txt, xml
Other mp4, swf, wav, ogg. mp3

Rich content files types, such as Microsoft Word and PDFs, can be used as article attachments but cannot be theme assets.

Usage

Once you’ve added theme assets to your theme they can be referenced in page templates and stylesheets.

Using the {{asset}} helper, you can reference theme assets within page templates.

The helper accepts one parameter, the filename of the asset.

<img src="{{asset 'background-image.png'}}" alt="Background image">

The following additional attributes are supported:

  • prefix (optional) adds a prefix to the filename.
  • suffix (optional) adds a suffix to the filename.

Using theme assets in JavaScript

If you need to access one or more assets in JavaScript, you can use page templates to expose them using the {{asset}} within a <script> tag. The example below illustrates how to access the url of an image in your assets/ folder:

<script type="text/javascript">
  var backgroundImage = "{{asset 'background-image.png'}}";
</script>

You can access theme assets within CSS using dynamic variables, which are generated automatically based on the asset filename. Continuing with the example above, if you wanted to access the background-image.png image URL within CSS you’d used the variable name $assets-background-image-png:

.class-name {
  background-image: url($assets-background-image-png);
}

Note the file extension is included within the generated variable name.

Alternatively you could write your custom CSS within a <style> tag in one of your page templates and use the {{asset}} helper:

<style>
  .class-name { 
    background: url("{{asset 'background-image.png'}}");
  }
</style>

Custom heading and text fonts can also be added to your theme using these variables:

@font-face {
  font-family: 'Webfont';
  src: url('$assets-webfont-eot');
  src: url('$assets-webfont-eot?#iefix') format('embedded-opentype'),
       url('$assets-webfont-woff2') format('woff2'),
       url('$assets-webfont-woff') format('woff'),
       url('$assets-webfont-ttf') format('truetype'),
       url('$assets-webfont-svg#webfont') format('svg');
  font-weight: normal;
  font-style: normal;
}

Use-cases

Within an {{each}} loop you can use the @index parameter, which represents the position of the object within its collection, or any other object property to reference images.

For example, when looping over the categories collection on the Home page you could use the following code to dynamically generate a reference to assets for use as category images:

{{#each categories}}
  <img src="{{asset @index prefix='category-' suffix='.svg'}}" alt="{{name}}">
{{/each}}

To have the images appear, they’d need to be added to the assets/ directory and given the following filenames:

theme/
└── assets/
  └── category-0.svg
  └── category-1.svg
  └── category-2.svg
  └── ...

Questions or feedback about this article? Let us know