Ghost: RetinaJS integration

In this post, I will show you how to quickly make your Ghost blog retina-ready.

If you are new to the retina thing, please read the Wikipedia page so you know what we are talking about.

Step 1: make your images retina-ready

I won't explain the whole thing about how to make your images retina-ready but this article covers the most of it.

Whether or not you are using the provided Photoshop export script, just make sure you save your files with @{factor}x.{ext} instead of _{factor}x.{ext}.
Where:

  • {factor} is the image dimension factor
  • {ext} is the file extension

Example: don't save my_photo_2x.png but my_photo@2x.png.

Step 2: upload your images

Make sure your retina-ready images have all the same name (excluding the @{factor}x name suffix) and also, make sure they are all in the same directory!

If you have an image uploaded as http://res.cloudinary.com/eexit-cloudinary/image/upload/t_blog/blog/photo.jpg, then upload the retina versions of that picture in the same directory:

  • http://res.cloudinary.com/eexit-cloudinary/image/upload/t_blog/blog/photo@2x.jpg
  • http://res.cloudinary.com/eexit-cloudinary/image/upload/t_blog/blog/photo@3x.jpg
  • http://res.cloudinary.com/eexit-cloudinary/image/upload/t_blog/blog/photo@4x.jpg

If you can't do that because you can't access to your server, the alternative way is to re-upload all images, including the non-retina one so they all lie in the same directory.

Step 3: installation

In the Blog Header section of your Ghost Code Injection page, add jQuery if you don't have it already:

<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.0.0/jquery.min.js"></script>

Download and save into your current theme JavaScript asset path the next release (should be >=2.0.0[1]) of RetinaJS.

In the Blog Footer section, add the <script> tag that imports it:

<script type="text/javascript" src="/assets/js/retina.min.js"></script>

Once RetinaJS is imported, copy and paste the following script snippet after your RetinaJS import:

<script type="text/javascript">
// Order matters!!
$('.post.tag-retina img').attr('data-rjs', 2);
$('.post.tag-retina-hd img').attr('data-rjs', 3);
$('.post.tag-retina-4k img').attr('data-rjs', 4);
</script>

Installation done.

Bonus

If your design is responsive, you might add the following code to your CSS file:

img {
  max-width: 100%;
  width: auto;
  height: auto;
}

Step 4: use it

At this point, you have:

  1. Uploaded all retina-ready images for the posts you want
  2. Installed the RetinaJS support

As of now, no post image is displayed as its homolog retina version. Maybe there are some posts you want to display regular images (non-retina) while other with beautiful photos with retina and why not retina 4K if you don't mind the bandwidth usage.

Very easy:

  • For retina posts: add the retina tag to your post (will load @2x or lower)
  • For retina HD posts: add retina-hd (will load @3x or lower)
  • For retina 4K: add retina-4k (will load @4x or lower)

Note: add only the tag of the higher retina version available for your post. RetinaJS assumes that if you uploaded a retina HD version (@3x) of an image, the subsequent lower resolution versions are also available.

Save your post tags and you're done.
Enjoy your HD blog now!


When I wrote the article, the next major version of RetinaJS wasn't released yet. The RetinaJS says it' version 1.5.0 but it should be released as 2.0.0. ↩︎