Assets - Ghost Developer Docs
https://docs.ghost.org/themes/assets • 330 KB fetched
Open original page
Assets - Ghost Developer Docs
Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Skip to main content
Ghost Developer Docs home page
Search...
⌘ K
* Sign in
* Get Started
* Get Started
Search...
Navigation
Themes
Assets
Home
Documentation
Migration Guides
*
Tutorials
*
Developer Forum
Getting Started
* Introduction
* Installation
* Hosting Guide
* Updates & Versions
Core Concepts
* Overview
* Architecture
* Configuration
* Staff Users
* Publishing
* Memberships
* Recommendations
* Newsletters
* Security
Themes
* Overview
* Structure
* Contexts
* Assets
* Helpers
* Content
* Search
* Share
* Members
* Routing
* Custom Settings
* GScan
Advanced Tools
* Ghost CLI
* Content API
* Admin API
* JAMstack
* Webhooks
Resources
* FAQ
* Breaking Changes
* Contributing
* LLM
* License
* Logos
* Trademark
On this page
* Responsive images configuration
* Using image sizes
* Converting images to smaller image types
* Compatibility
Themes
Assets
Ghost themes support automatic image resizing, allowing you to use a minimal handlebars helper to output different image sizes.
Ghost automatically compresses and resizes images added to your post content and generates automatic responsive assets for maximum performance.
For all other images, such as feature images and theme images, the responsive images feature builds responsive image srcsets into your theme, and displays scaled down images when required to improve your site’s overall performance.
Responsive images configuration
Responsive images can be defined in the package.json file. Ghost automatically generates copies of images at the specified sizes, and works like a cache, so the image sizes can be changed at any time. It’s recommended to have no more than 10 image sizes so media storage doesn’t grow out of control.
Here’s a sample of the image sizes in Ghost’s default Casper theme .
// package.json
"config" : {
"image_sizes" : {
"xxs" : {
"width" : 30
},
"xs" : {
"width" : 100
},
"s" : {
"width" : 300
},
"m" : {
"width" : 600
},
"l" : {
"width" : 1000
},
"xl" : {
"width" : 2000
}
}
}
Using image sizes
Once image sizes are defined, pass a size parameter to the {{img_url}} helper in your theme to output an image at a particular size.
< img src= " {{ img_url feature_image size= "s" }} " >
To build full responsive images create html srcsets passing in multiple image sizes, and let the browser do the rest.
Here’s an example from Ghost default Casper theme implementation:
<!-- index.hbs -->
< img class= "post-image"
srcset= " {{ img_url feature_image size= "s" }} 300w,
{{ img_url feature_image size= "m" }} 600w,
{{ img_url feature_image size= "l" }} 1000w,
{{ img_url feature_image size= "xl" }} 2000w"
sizes= "(max-width: 1000px) 400px, 700px"
src= " {{ img_url feature_image size= "m" }} "
alt= " {{ #if feature_image_alt }}{{ feature_image_alt }}{{ else }}{{ title }}{{ /if }} "
/>
Converting images to smaller image types
Pass a format parameter to the {{img_url}} helper in your theme to output an image in a particular image format. This only works in combination with the size parameter.
{{ img_url feature_image size= "s" format= "webp" }}
By converting an image from PNG, GIF, or JPEG to WebP, you can reduce its size by ~25% without any visible loss of quality. An even better image compression can be obtained with the AVIF format, but this isn’t supported in all browsers (and doesn’t support animation yet).
Note that while image conversion changes the file type, the file extension stays the same. For example, an AVIF image will retain the .jpg extension.
WebP is supported by all modern browsers, but we recommend to always add a fallback to the original file type to achieve wider browser support. Use a <picture> tag for this, which allows the browser to choose the first format it supports:
< picture >
<!-- Serve the AVIF format if the browser supports it -->
<!-- Remove this block when using animated images as feature images -->
< source
srcset= " {{ img_url feature_image size= "s" format= "avif" }} 300w,
{{ img_url feature_image size= "m" format= "avif" }} 600w,
{{ img_url feature_image size= "l" format= "avif" }} 1000w,
{{ img_url feature_image size= "xl" format= "avif" }} 2000w"
sizes= "(min-width: 1400px) 1400px, 92vw"
type= "image/avif"
>
<!-- Serve the WebP format if the browser supports it -->
< source
srcset= " {{ img_url feature_image size= "s" format= "webp" }} 300w,
{{ img_url feature_image size= "m" format= "webp" }} 600w,
{{ img_url feature_image size= "l" format= "webp" }} 1000w,
{{ img_url feature_image size= "xl" format= "webp" }} 2000w"
sizes= "(min-width: 1400px) 1400px, 92vw"
type= "image/webp"
>
<!-- Serve original file format as a fallback -->
< img
srcset= " {{ img_url feature_image size= "s" }} 300w,
{{ img_url feature_image size= "m" }} 600w,
{{ img_url feature_image size= "l" }} 1000w,
{{ img_url feature_image size= "xl" }} 2000w"
sizes= "(min-width: 1400px) 1400px, 92vw"
src= " {{ img_url feature_image size= "xl" }} "
alt= " {{ #if feature_image_alt }}{{ feature_image_alt }}{{ else }}{{ title }}{{ /if }} "
>
</ picture >
Compatibility
Unlike other platforms, there’s no manual work needed to manage image sizes in your theme, it’s all done in the background for you.
Image sizes are automatically generated for all feature images and theme images, and regenerated whenever an image is changed, the image sizes configuration is changed, or when theme changes are made. Images are generated on the first request for each image at a particular size.
Dynamic image sizes are not compatible with externally hosted images (except inserted images from Unsplash ). If you store your image files on a third party storage adapter, then the image URL returned will be determined by the external source.
Suggest edits Raise issue
Error
Overview
github twitter bluesky reddit
Powered by This documentation is built and hosted on Mintlify, a developer documentation platform
Links found on this page
- /llms.txt [direct]
- Skip to main content [direct]
- Ghost Developer Docs home page [direct]
- Sign in [direct]
- Get Started [direct]
- Home [direct]
- Documentation [direct]
- Migration Guides [direct]
- Tutorials [direct]
- Developer Forum [direct]
- Installation [direct]
- Hosting Guide [direct]
- Updates & Versions [direct]
- Overview [direct]
- Architecture [direct]
- Configuration [direct]
- Staff Users [direct]
- Publishing [direct]
- Memberships [direct]
- Recommendations [direct]
- Newsletters [direct]
- Security [direct]
- Overview [direct]
- Structure [direct]
- Content [direct]
- Search [direct]
- Share [direct]
- Members [direct]
- Routing [direct]
- Custom Settings [direct]
- GScan [direct]
- Ghost CLI [direct]
- Webhooks [direct]
- FAQ [direct]
- Breaking Changes [direct]
- Contributing [direct]
- LLM [direct]
- License [direct]
- Logos [direct]
- Trademark [direct]
- the image sizes in Ghost’s default Casper theme [direct]
- {{img_url}} [direct]
- full responsive images [direct]
- example from Ghost default Casper theme [direct]
- isn’t supported in all browsers [direct]
- Unsplash [direct]
- Suggest edits [direct]
- Raise issue [direct]
- Error [direct]
- Overview [direct]
- github [direct]
- twitter [direct]
- bluesky [direct]
- reddit [direct]
- Powered by This documentation is built and hosted on Mintlify, a developer documentation platform [direct]