Sections

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

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 assets to your theme they can be referenced natively in page templates and stylesheets.

Templates

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.

Category and section images

Using these attributes, you can create dynamic references to assets for use with categories, sections or other Help Center properties. 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 dynamically generate the src attribute for an image.

For example, the following code loops though the categories collection on the Home page and generates the image src attribute using the category’s position (@index) in the collection:

{{#each categories}}
  <img class="h-8" 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
  └── ...

To use the category ID in the filename instead of the position in the collection, you’d simply replace @index with id.

For more complex use-cases involving image assets, our Images plugin is available.

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>

Stylesheets

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;
}