Assets

Learn how to bundle static files with your theme and reference them from Liquid templates and CSS using the asset_url filter.

Assets are static files bundled with a theme.

They typically include images, fonts, icons and other resources required to render the website. Every asset is packaged together with the theme and made available through the asset_url Liquid filter.

Asset directory

All assets belong in the assets directory.

assets/
  logo.svg
  hero.jpg
  favicon.ico
  fonts/
    Inter-Regular.woff2

Subdirectories are fully supported and are preserved when packaging the theme.

Referencing assets

Assets should always be referenced using the asset_url filter.

<img src="{{ 'logo.svg' | asset_url }}" alt="Logo">

Assets inside subdirectories are referenced using their relative path.

<link
  rel="preload"
  href="{{ 'fonts/Inter-Regular.woff2' | asset_url }}"
  as="font"
  crossorigin
>

Using asset_url allows Masthead to generate the correct URL regardless of where the theme is installed.

CSS assets

Assets can also be referenced from theme.css.

.hero {
  background-image: url("{{ 'hero.jpg' | asset_url }}");
}

The same filter works in CSS and Liquid templates.

Uploads vs assets

Themes distinguish between assets and uploads.

Assets are bundled with the theme and are shared by every site using it.

Examples include:

Logos
Icons
Fonts
Decorative images

Uploads belong to a specific site and are managed by the site owner.

Examples include:

Blog images
Documents
User photos
Downloadable files

If a file should be customizable by the site owner, it should usually be an upload referenced through a file token rather than a bundled asset.

Packaging

Everything inside the assets directory is automatically included when packaging a theme.

No additional configuration is required.

Next steps

During development, themes are previewed using local content and configuration.

The next guide explains how to configure preview content and simulate a complete Masthead site locally.