How to Load Smaller Images on your Ghost Home Page

Post cover image

With Ghost not yet having image management, one problem you may come across is when you upload a cover image for your post, that image may be too large for the smaller area on your home page.

We had this problem on this site where the home page uses a bunch of the cover images, but they are only 200px on the home page and 1500px on the post. So, our home page was loading these huge images for tiny containers. This was obviously destroying performance.

So, how can you fix this problem. You can either upload your images to a service that resizes them, put your blog behind a cdn that does image resizing like cloudflare, or, you can do what we did, and set your nginx to automatically resize the images on the home page for you.

Here is how you can do the same for free and get much greater performance:

Note: Must be self hosted or have access to your Nginx configuration for this to work

  1. We are going to use the Nginx module ngx_http_image_filter_module. This should be built in by default, but double check to see if your Nginx already has it built in using the following command (we host on DigitalOcean and it was already built as a part of our Nginx):

     nginx -V

    It will show up in the list that is shown if it is built in.

    Image filter module in terminal

    If it is not apart of your Nginx, it needs to be added. Here is a link to the official docs for the module.

  2. Open up the Nginx conf for your specific site. This is typically located in /etc/nginx/sites-available/your_site.conf

    vi /etc/nginx/sites-available/your_site.conf
  3. Now, what we are going to do is set up a dynamic way for us to be able to resize the images on the fly. We are going to do this by sending URL parameters to Nginx to interpret.

    For example, instead of a image link being /content/images/image.jpg, we are going to use /content/images/image.jpg?w=200&h=200&q=50.

    So, w means width, h means height, and q means quality. We are going to be able to send these through with any image we want and it will be resized to what we send through. If we don't send a certain property, or send nothing at all, the properties not sent will stay the way it is.

    Inside your Nginx conf file, you should see a couple server blocks already. Head to the very bottom of your file and we are going to add a location block for the photos.

    Here is the full entry we are going to add (feel free to just copy and paste) and then we will walk through it.

     location ^~ /content/images/ {
         set $width "-";
         set $height "-";
         set $quality "95";
         if ($arg_w != '')
             set $width $arg_w;
         if ($arg_h != '')
             set $height $arg_h;
         if ($arg_q != '')
             set $quality $arg_q;
         proxy_pass http://localhost:2368;
         image_filter resize $width $height;
         image_filter_jpeg_quality $quality;

    So, what this is doing is saying anything with a location that starts with /content/images/ (which is where all post images are stored) will run through this code.

    To start, we set the Nginx variables to their default so if nothing is passed for that variable, nothing will be changed.

    Next we check to see if each parameter exists. if ($arg_w != '') is checking, if the argument w does not equal '' (which means nothing), then set it to what was passed. So, if nothing was passed, that will be skipped.

    After each of the if statements, we pass the proxy so the request still goes to Ghost. If you are running Ghost on a different port, then change the 2368 to whatever port your using.

    Then lastly, we run the resize command to resize whatever we passed, and then we run it through the quality command to change the quality if we want to.

  4. Once that is in place, we need to restart Nginx:

     service nginx restart
  5. You can test to see that it worked by going to one of your post images in your browser, and then adding ?w=200 to it and see that it loads the small image.

    For example, here is the resized version of this posts cover image.

  6. Now, in your theme, on your home page (either home.hbs or index.hbs depending on your theme), you can change the image source to include the variables so this change will be made as it loads each image for the home page.

    Here is an example of wanting to change the image to a width of 200 and the quality to 50%:

     <img src="{{image}}?w=200&q=50">
  7. Restart Ghost once you have it in your theme and you will be loading smaller images!

     service ghost restart

We use this all over our home page, but since we set it up via Nginx, you can actually use this on any post image you want to.

If you to see the way we use it, you can check out the code we use on our github.

Leave a comment or hit us up on Twitter if you have any questions or need any help!