Do more with images on the Contentful platform

If you work with images on Contentful, you’re in for a treat! In the last couple of weeks, we released some awesome features for working with images. In short order, you can now add assets to markdown fields, edit images with URL magic and tap into the Getty Images API for high-quality editorial and creative photos.

Assets are coming to Markdown fields

After we rolled out support for Markdown formatting in text fields, many of you asked us to go one step further and enable inserting of images from the asset module. In our internal discussions, we were very cautious about embracing this idea, primarily because we don't want you to fall victims to some of the more outdated web-development ideas.

Here is what we meant with that: as we’ve said so many times before, Contentful is a screen-agnostic platform that allows you reuse your content across a whole universe of devices and mediums. Unfortunately, this approach only works if content creators learn to ignore what years of working with WYSIWYG type of editors has taught them.

In a way, Contentful is a YNKWYG - "You Never Know What You Get" - type of editor. And it is a good thing too. Since online content can be consumed in so many unexpected ways these days - from e-readers and car navigation to smart fridges and wearables, not getting hung up on how your content looks is something of a competitive advantage.

The importance of seeing beyond the immediate picture is especially relevant in the case of images, which lose their emotional impact when not optimized properly for screen resolution and aspect ratios.

It is for this reason that we visualize any image inserted into a markdown-field in a scaled-down version set in a grey canvas box. The message we want to send is: "The visible image is just a placeholder. Actual design decisions are made on specific devices by your design & development team, not by a lonely editor in the editor interface."

Adding images to the field

Coming down to practicalities, to insert an image, just click a paperclip icon and choose a desired image in the dialogue box. Remember, you can use all kinds of search operators to help you filter through the large numbers of images. The asset of your choice is then inserted below the current paragraph, using standard markdown syntax for images. You can preview images by switching the text field to the preview mode.

Editing images on the fly

And now for the "design decisions" that will help you properly display images on a variety of devices. We are very excited to roll out changes to the Content Delivery API making it super easy to experiment with image sizes, resolutions and aspect ratios.

As long as your images are hosted on our domain (and all of our assets are automatically put there), you can specify the desired image output by using a combination of URL query parameters.

Since the most frequent problem content creators have is scaling images down, let’s look at image resizing first. By default, whenever you specify desired w and h parameters, your image will be scaled down to fit the bounding box. Mind you, the image is not stretched, skewed or enlarged, but instead intelligently fit into the area defined by you. The way it works is that you add optional parameters at the end of URL, for example, "". Here is the kind of image you will get by specifying a bounding box of 300*300 px:


Image scaling

To change the default way in which your image responds to the w and h parameters, attach the 'fit' parameter to the asset’s URL. Now the image will be stretch on the short side to fill the entire bounding box.


Image scaling

The 'focus' parameter determines where the fit parameter should focus on. It takes values such as right, left, top and bottom or combine them like bottom_left or top_right. If you work with human photography, you can also choose to focus on faces. To clearly see the effect of focusing on a specific area, I added the crop function below:


Image scaling

Alternatively, fit can take on values like 'thumb' and 'pad'. The former one request a thumbnail image to be generated, e.g. your original image will be cropped to fit the specified dimensions. Meanwhile, padding will add margins on the shorter side to fill set boundaries. To highlight the paddings, I also added red background color to the parameter list. See how it looks in practice:


Image scaling

For a more retro look, try 'radius' parameter - it adds rounded corners to your image. The higher the value, the more enclosed in a circle your image will be. All Emily Brontë fans out there, just imagine the wonderful family albums you can produce now!


Image scaling

Finally, for all of you worrying about the latency of your pages and apps, our API also allows a 'q' parameter to be passed along to define the value of JPEG compression (possible values are between 1 and 100). Meanwhile the fm parameter can be used to change the format to either "png" or "jpg".


Image scaling

One last final word of caution, we recommend that you perform URL-triggered actions only on final images. The reason is simple: if you happen to update an original image, say, by adding a high-res picture or replacing original with something different altogether, your edited image WILL NOT update automatically. Instead, you'd need to add parameters used for image-manipulation to a newly republished URL and insert it in the right place manually.

Getty Images integration

We know that many of our clients, who happen to be in the media publishing business, have a very close working relationship with licensed image banks. We decided to make their lives a bit easier by building a direct integration with the Getty Images API.

The result is that customers on an Enterprise plan can search, browse and insert images from authorized Getty collection without leaving the Asset Module. We are convinced that this move will considerably simplify the work of busy editors.

Please note that this a premium feature, which is available by a separate request and is subject to customers being on an enterprise plan and having a registered account + a valid licensing agreement with Getty Images. To activate this feature, you will need to obtain the following API credentials from Getty Images:

  • Client ID / API key;
  • Client secret;
  • username;
  • password;

You can find more information about how resource owner flow works on Getty Images public repo.

Thanks for reading, we hope you enjoy these new additions!

Image Credits: Ermin Celikovic

Blog posts in your inbox

Subscribe to receive most important updates. We send emails once a month.