Developer docs

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}}"
/>

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. If you insert images from Unsplash or you store your image files on a third party storage adapter then the image url returned will be determined by the external source.