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. You can now add assets to markdown fields and edit images with URL magic!

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."

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 images.contentful.com (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, https://images.contentful.com/folder/subfolder/image.jpg?w=400&h=300. Here is the kind of image you will get by specifying a bounding box of 300*300 px:

?w=300&h=300

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.

?fit=scale&w=300&h=300

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:

?fit=crop&w=250&h=250&f=bottom_right

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:

fit=pad&w=200&h=300&fm=jpg&bg=red

For a more retro look, try the r (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!

?fit=thumb&f=face&r=20

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.

?fm=jpg&q=5

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.

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

You can read more about using images in Contentful in our "Creator's guide to image file formats" article.

Image Credits: Ermin Celikovic

Subscribe for updates

Build better digital experiences with Contentful updates direct to your inbox.