Sections

Assets

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

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

Assets can be referenced natively in page templates and stylesheets. For more complex use-cases involving image assets, our Images plugin is available.

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.

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:

└── 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.

Templates can also be used to access theme assets within JavaScript, using a <script> tag:

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

Stylesheets

Using dynamic variables, you can reference theme assets within CSS and CSS files. For example, an image with the filename background-image.png can be referenced using the variable name $assets-background-image-png:

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

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