Images
Add an image to your content using a simple piece of syntax. Images are automatically optimized — they are compressed and converted to a modern format (WebP) for fast loading.
Syntax
- The text between
![and]is the alt text — a short description of what the image shows. This is important for accessibility (screen readers use it) and also controls the image size (see below). - The URL between
(and)is the direct link to the image.
Examples
Basic image
Type this in Contentful:
What you’ll see: The image displayed at its natural size, fitting within the content area.
Small image
Type this in Contentful:
What you’ll see: The image displayed at a small size (about 32px wide). Useful for icons or small logos.
Medium image
Type this in Contentful:
What you’ll see: The image displayed at a medium size (about 240px wide). Good for profile photos or illustrative images beside text.
Large image
Type this in Contentful:
What you’ll see: The image displayed at a large size (about 384px wide).
Custom pixel size
Type this in Contentful:
What you’ll see: The image displayed at exactly 300px wide.
Options / Variations
You can control the image size by adding a size keyword to the end of the alt text, separated by a hyphen:
| Alt text format | Image size |
|---|---|
![Description] | Natural size (fills the content area) |
![Description-small] | Small (~32px wide) |
![Description-medium] | Medium (~240px wide) |
![Description-large] | Large (~384px wide) |
![Description-300px] | Custom width (300px in this example) |
The size keyword must be at the very end of the alt text, after a hyphen. The description before the hyphen is what appears as the accessible label (e.g., Profile photo becomes the alt text, -300px sets the size).
Tips
- Always write a meaningful description in the alt text — even if you’re using a size keyword, make the description before the hyphen descriptive (e.g.,
Team photo-medium, not just-medium). - Images from Contentful’s media library are automatically optimized. You don’t need to do anything extra — just paste the image URL.
Common Mistakes
No URL in the parentheses
Wrong: ![My photo]
Right: 
The image URL inside () is required. Without it, the image won’t display.
Spaces inside the brackets or parentheses
Wrong: 
Right: 
Keep the syntax tight — no extra spaces inside the [] or ().
Wrong size keyword format
Wrong: ![Photo - medium] or ![Photo_medium] or ![medium-Photo]
Right: ![Photo-medium]
The size keyword must be at the end of the alt text, preceded directly by a hyphen with no spaces. The order matters: description first, then hyphen, then size.