Assets & CDN Filters
Generate asset URLs, process images with CDN, and create HTML tags for resources
Nimbu provides powerful CDN integration for assets, with automatic image processing, optimization, and responsive image generation.
Asset URLs
asset_url
Generate URL for theme assets:
{{ 'style.css' | asset_url }}
<!-- Output: /assets/themes/theme-slug/style.css -->
<link rel="stylesheet" href="{{ 'main.css' | asset_url }}">
<script src="{{ 'app.js' | asset_url }}"></script>theme_image_url
Get theme image URL:
{{ 'logo.png' | theme_image_url }}
<img src="{{ 'banner.jpg' | theme_image_url }}" alt="Banner">global_asset_url
Access global site assets:
{{ 'shared-logo.png' | global_asset_url }}
<img src="{{ 'favicon.ico' | global_asset_url }}">Image Processing with CDN
filter
Apply comprehensive image transformations:
{{ image.url | filter, width: '800px', height: '600px' }}
{{ product.image.url | filter, width: '400px', cropping: 'fill' }}
{{ photo.url | filter, width: '1200px', height: '800px', cropping: 'fill', gravity: 'north', format: 'jpg', quality: 85 }}Parameters:
| Parameter | Description | Values |
|---|---|---|
width | Target width | '300px', '1200px' |
height | Target height | '400px', '800px' |
cropping | Resize mode | 'fit' (default), 'fill', 'scale', 'crop' |
gravity | Which part of the image to keep when cropping | 'center' (default), 'north', 'south', 'east', 'west', 'north_east', 'north_west', 'south_east', 'south_west' |
effect | Visual effect | 'grayscale', 'sepia', 'vignette' |
format | Output format | 'jpg', 'png', 'webp', 'gif', 'tiff', 'bmp' |
quality | Compression quality, only used together with format | 1-99 |
alpha | Opacity in percent; the output becomes PNG | 0-99 |
Write width and height as strings ending in px. Values the CDN does not know are dropped without an error: an unknown cropping falls back to fit, an unknown gravity to center, an unknown format keeps the original format.
Without format, the image keeps its own format and quality is ignored. To compress a JPEG, pass both: format: 'jpg', quality: 80. With format but no quality, the encoder's default quality is used.
Cropping Modes:
fit- Fit within width and height, keep the aspect ratiofill- Cover width and height, keep the aspect ratio, then crop the overflow (gravitypicks the part that stays)scale- Resize to exactly width and height, ignore the aspect ratiocrop- No resizing: cut a width by height area out of the original, positioned bygravity
Gravity Options:
center- Center of imagenorth,south,east,west- Directionalnorth_east,north_west,south_east,south_west- Corners
There is no face detection. For portraits, gravity: 'north' usually keeps heads in the frame.
grayscale
Convert image to grayscale:
{{ image.url | grayscale }}
<img src="{{ product.image.url | grayscale }}" alt="B&W {{ product.name }}">Image Tag Helpers
image_tag
Generate complete image tag:
{{ 'logo.png' | theme_image_url | image_tag }}
<!-- Output: <img src="/assets/.../logo.png" alt="Logo"> -->
{{ image.url | image_tag, alt: product.name, class: 'product-image' }}
{{ photo | image_tag, alt: "Team photo", width: 800, height: 600 }}With Lazy Loading:
{{ image.url | image_tag, loading: 'lazy', class: 'lazy-image' }}Responsive Images
Srcset Generation
Create responsive image sets:
{% assign image_400 = product.image.url | filter, width: '400px' %}
{% assign image_800 = product.image.url | filter, width: '800px' %}
{% assign image_1200 = product.image.url | filter, width: '1200px' %}
<img
src="{{ image_800 }}"
srcset="{{ image_400 }} 400w,
{{ image_800 }} 800w,
{{ image_1200 }} 1200w"
sizes="(max-width: 600px) 400px,
(max-width: 1200px) 800px,
1200px"
alt="{{ product.name }}"
loading="lazy">Picture Element
Art direction with different crops:
<picture>
<source
media="(max-width: 600px)"
srcset="{{ image.url | filter, width: '600px', height: '400px', cropping: 'fill', gravity: 'north' }}">
<source
media="(max-width: 1200px)"
srcset="{{ image.url | filter, width: '1200px', height: '600px', cropping: 'fill' }}">
<img
src="{{ image.url | filter, width: '1920px', height: '800px', cropping: 'fill' }}"
alt="{{ image.title }}">
</picture>Stylesheet and Script Tags
stylesheet_tag
Generate stylesheet link:
{{ 'theme.css' | stylesheet_tag }}
<!-- Output: <link href="https://<cdn>/.../stylesheets/theme.css" media="screen" rel="stylesheet" type="text/css"/> -->
{{ 'custom.css' | stylesheet_tag: media: 'print' }}
{{ 'print.css' | stylesheet_tag: media: 'print', preload: true }}
<!-- Forces a `Link: <url>; rel=preload; as=style` response header (Early Hints),
even for stylesheets that are not render-blocking. No HTML attribute is emitted.
Only same-host and Nimbu CDN stylesheets are preloaded. -->javascript_tag
Generate script tag:
{{ 'app.js' | javascript_tag }}
<!-- Output: <script src="https://<cdn>/.../javascripts/app.js" type="text/javascript"></script> -->
{{ 'analytics.js' | javascript_tag: defer: true }}
{{ 'polyfill.js' | javascript_tag: async: true }}
{{ 'tracking.js' | javascript_tag: consent: 'analytics' }}
<!-- Opt-in script: only runs after the visitor accepts "analytics" in the consent manager -->Pass a file name, not an asset_url: the tags look the file up in the theme's stylesheets/ or javascripts/ folder themselves. Values starting with / or http: are used as-is. For external https:// scripts and stylesheets, write the <script> or <link> tag yourself.
Practical Examples
Product Images with Variants
<div class="product-gallery">
<!-- Main image -->
<div class="main-image">
{% if product.images.first %}
{% assign main_image = product.images.first.url %}
<img
src="{{ main_image | filter, width: '800px', height: '800px', cropping: 'fill' }}"
srcset="{{ main_image | filter, width: '400px', height: '400px', cropping: 'fill' }} 400w,
{{ main_image | filter, width: '800px', height: '800px', cropping: 'fill' }} 800w,
{{ main_image | filter, width: '1200px', height: '1200px', cropping: 'fill' }} 1200w"
sizes="(max-width: 768px) 400px, 800px"
alt="{{ product.name }}"
loading="eager">
{% endif %}
</div>
<!-- Thumbnails -->
<div class="thumbnails">
{% for image in product.images %}
<button class="thumbnail" data-index="{{ forloop.index0 }}">
<img
src="{{ image.url | filter, width: '100px', height: '100px', cropping: 'fill' }}"
alt="{{ product.name }} - Image {{ forloop.index }}"
loading="lazy">
</button>
{% endfor %}
</div>
</div>Hero Banner with Optimizations
<section class="hero">
{% if page.hero_image %}
<picture>
<!-- Mobile: Portrait crop -->
<source
media="(max-width: 768px)"
srcset="{{ page.hero_image.url | filter, width: '768px', height: '1024px', cropping: 'fill', gravity: 'center', format: 'webp' }} 768w"
type="image/webp">
<!-- Tablet: Landscape -->
<source
media="(max-width: 1200px)"
srcset="{{ page.hero_image.url | filter, width: '1200px', height: '600px', cropping: 'fill', format: 'webp' }} 1200w"
type="image/webp">
<!-- Desktop: Full width -->
<source
srcset="{{ page.hero_image.url | filter, width: '1920px', height: '800px', cropping: 'fill', format: 'webp', quality: 85 }} 1920w"
type="image/webp">
<!-- Fallback JPG -->
<img
src="{{ page.hero_image.url | filter, width: '1920px', height: '800px', cropping: 'fill', format: 'jpg', quality: 85 }}"
alt="{{ page.hero_title }}"
loading="eager">
</picture>
{% endif %}
<div class="hero-content">
<h1>{{ page.hero_title }}</h1>
<p>{{ page.hero_subtitle }}</p>
</div>
</section>Team Member Cards
<div class="team-grid">
{% for member in channels.team.all %}
<div class="team-card">
{% if member.photo %}
<div class="photo">
<img
src="{{ member.photo.url | filter, width: '300px', height: '300px', cropping: 'fill', gravity: 'north' }}"
alt="{{ member.name }}"
loading="lazy">
</div>
{% else %}
<div class="photo placeholder">
<img src="{{ 'team-placeholder.png' | theme_image_url }}" alt="{{ member.name }}">
</div>
{% endif %}
<h3>{{ member.name }}</h3>
<p class="role">{{ member.role }}</p>
</div>
{% endfor %}
</div>Background Images
<section
class="cta-section"
style="background-image: url('{{ page.background.url | filter, width: '1920px', format: 'jpg', quality: 75 }}')">
<div class="cta-content">
<h2>{{ page.cta_title }}</h2>
<a href="{{ page.cta_link }}" class="btn">{{ page.cta_text }}</a>
</div>
</section>Asset Preloading
<head>
<!-- Preload critical images -->
<link
rel="preload"
as="image"
href="{{ page.hero_image.url | filter, width: '1920px', format: 'webp' }}"
type="image/webp">
<!-- Preload fonts -->
<link
rel="preload"
as="font"
href="{{ 'Inter-Regular.woff2' | asset_url }}"
type="font/woff2"
crossorigin>
<!-- Stylesheets -->
{{ 'theme.css' | stylesheet_tag }}
<!-- Critical JS -->
{{ 'critical.js' | javascript_tag }}
</head>Image Gallery with Lightbox
<div class="image-gallery">
{% for image in page.gallery %}
<a
href="{{ image.url | filter, width: '1920px', format: 'jpg', quality: 90 }}"
class="gallery-item"
data-lightbox="gallery">
<img
src="{{ image.url | filter, width: '400px', height: '300px', cropping: 'fill' }}"
alt="{{ image.title }}"
loading="lazy">
</a>
{% endfor %}
</div>Performance Best Practices
1. Use Appropriate Image Formats
<!-- ✅ Good: Modern formats with fallback -->
<picture>
<source srcset="{{ image.url | filter, width: '800px', format: 'webp' }}" type="image/webp">
<source srcset="{{ image.url | filter, width: '800px', format: 'jpg' }}" type="image/jpeg">
<img src="{{ image.url | filter, width: '800px' }}" alt="...">
</picture>
<!-- ⚠️ Acceptable for simple cases -->
<img src="{{ image.url | filter, width: '800px' }}" alt="...">2. Optimize Quality Settings
<!-- ✅ Good: Re-encode at a lower quality -->
{{ image.url | filter, width: '1200px', format: 'jpg', quality: 80 }}
<!-- ❌ Bad: quality without format is ignored -->
{{ image.url | filter, width: '1200px', quality: 80 }}3. Lazy Load Below the Fold
<!-- Above the fold: Eager loading -->
<img src="{{ hero.url | filter, width: '1920px' }}" loading="eager" alt="Hero">
<!-- Below the fold: Lazy loading -->
<img src="{{ image.url | filter, width: '800px' }}" loading="lazy" alt="...">4. Pick the Gravity for People Photos
<!-- ✅ Good: Keep the top of a portrait, where the head usually is -->
{{ member.photo.url | filter, width: '300px', height: '300px', cropping: 'fill', gravity: 'north' }}
<!-- ⚠️ Default center crop: might cut off heads in tall photos -->
{{ member.photo.url | filter, width: '300px', height: '300px', cropping: 'fill' }}Next Steps
- Commerce - Shopping cart and product helpers
- Special Purpose - QR codes, analytics, utilities
- Pages - Working with page images
- Performance - Optimization strategies
Optimize and deliver assets effectively with Nimbu's CDN filters!