Ghost Image and Media — Optimization, Galleries and Image Cards

In this tutorial, you'll learn how to manage images and media in Ghost — uploading and inserting images, using image and gallery cards, optimizing images for performance, and managing your media library.

What You'll Learn

• Uploading images in the Koenig editor
• Using Image cards: alignment, captions, alt text
• Using Gallery cards for photo collections
• Image optimization: formats, compression, responsive sizes
• Ghost's built-in image processing (sharp)
• Custom image sizes and the {{img_url}} helper
• Setting feature images and focal points
• External image services and CDN integration
• Video and audio content in Ghost

Why It Matters

Images are the most impactful element on a web page for both user experience and performance. A well-optimized image loads quickly, looks sharp on all devices, and enhances comprehension. A poorly optimized image - too large, wrong format, missing alt text - slows down your site, hurts SEO, and makes your content less accessible. Ghost gives you good defaults, but knowing how to work with images intentionally makes your site faster and more professional.

Real-World Use

A travel photographer publishes photo essays on Ghost. Each post contains 15-20 high-resolution images. She uses Image cards with descriptive captions, Gallery cards for photo collections from each destination, and sets a focal point on each feature image so the most interesting part of the photo is always visible. She uses an S3 storage adapter so images are served from a CDN. The site loads fast despite being image-heavy.

Learning Path

flowchart LR
  A["Content Organization"] --> B["Image & Media
You are here"]:::current
  B --> C["Theme Basics"]
  C --> D["Handlebars Templates"]

  classDef current fill:#38bdf8,color:#0f172a,stroke-width:2px

Image Cards

The Image card is one of the most frequently used cards in the Koenig editor.

Inserting an Image

There are several ways to add an image:

1. Click the + button and select "Image" from the card menu.
2. Type /image in the editor and press Enter.
3. Drag and drop an image file directly into the editor.
4. Copy an image and paste it into the editor.

Image Card Options

After adding an image, click on it to see the toolbar:

• Alignment: Left, center, or full-width
• Caption: Text displayed below the image
• Alt text: Descriptive text for accessibility and SEO
• Link: Wrap the image in a clickable link
• Replace: Upload a different image
• Edit: Open the image in the Ghost image editor

Image Card Settings

In the right settings panel when an image is selected:

• Alt text: Describe what the image shows for screen readers and search engines
• Caption: Optional visible caption below the image
• Image URL: Direct link to the uploaded image file

Gallery Cards

Gallery cards display multiple images in a grid layout.

Creating a Gallery

1. Click the + button and select "Gallery."
2. Click to upload images or drag and drop multiple files.
3. Images appear in a responsive grid.
4. Add captions to individual images.

Gallery Display

The gallery card auto-arranges images in a masonry or grid layout depending on your theme. You can:

• Click images to view them in a lightbox (if your theme supports it)
• Reorder images by dragging
• Remove individual images

Feature Images

Every post and page can have a feature image - the main image that appears at the top of the content.

Setting a Feature Image

1. In the post editor, click the feature image area at the top.
2. Upload an image or select from existing uploads.
3. Click on the image to set a focal point.

Feature Image Focal Point

The focal point tells Ghost which part of the image is most important. When the image is cropped for different display sizes, the focal point stays visible.

To set a focal point:

1. Click the feature image to select it.
2. Click the "Set focal point" button.
3. Click on the image where the focal point should be.
4. Save.

Why focal points matter: A feature image displayed as a wide hero banner crops differently on desktop (16:9) vs mobile (4:5). Without a focal point, Ghost centers the crop, which might cut off the subject's face. With a focal point, Ghost centers on the face regardless of the crop ratio.

Ghost's Image Processing

Ghost uses the sharp Node.js library to process images on upload. It automatically:

1. Creates multiple size variants (for responsive images)
2. Optimizes JPEG and PNG compression
3. Converts to modern formats when appropriate
4. Strips metadata (EXIF data) for privacy

Generated Image Sizes

When you upload an image, Ghost creates these variants:

The {{img_url}} Helper

In your theme templates, you can request specific image sizes:

<!-- Original uploaded size -->
<img src="{{img_url feature_image}}">

<!-- Large variant -->
<img src="{{img_url feature_image size="l"}}">

<!-- Custom width -->
<img src="{{img_url feature_image width="800"}}">

<!-- Custom width and height -->
<img src="{{img_url feature_image width="800" height="600"}}">

<!-- WebP format (if supported) -->
<img src="{{img_url feature_image format="webp"}}">

Using the correct image size for each context improves page load speed. Use size="s" for card thumbnails and size="xl" for hero images.

Image File Management

Image Location

Uploaded images are stored in content/images/ within your Ghost installation directory. Ghost organizes them in a date-based folder structure:

content/images/
├── 2024/
│   ├── 01/
│   │   ├── my-image.png
│   │   └── another-image.png
│   └── 02/
│       └── travel-photo.jpg

Image Storage Options

• Local storage: Default. Images stored on your server.
• S3 storage: Images stored on Amazon S3 or compatible object storage.
• Google Cloud Storage: Images stored on Google Cloud Storage.
• Azure Storage: Images stored on Microsoft Azure Blob Storage.

Image Limits

• Maximum upload file size: Set by your server configuration (typically 10-50 MB)
• Ghost does not limit the total number of images
• Storage limits are determined by your hosting plan

Image Best Practices

Before Uploading

In the Editor

• Always set alt text on every image
• Add captions for context
• Set a focal point on feature images
• Use gallery cards for multiple related images

Video and Audio in Ghost

Ghost does not host video or audio files natively. You have two options:

Option 1: Embed External Video

Use the Embed card to include videos from YouTube, Vimeo, or other platforms:

1. Type /embed and press Enter.
2. Paste the video URL.
3. Ghost automatically creates an embed with the correct player.

Option 2: Self-Hosted Video

Upload video files to your storage or CDN and embed them via HTML:

1. Use an HTML card in the editor.
2. Add a <video> tag pointing to your hosted file.

<video controls width="100%">
  <source src="https://cdn.example.com/videos/tutorial.mp4" type="video/mp4">
  Your browser does not support the video tag.
</video>

Common Mistakes

1. Uploading images without alt text: Alt text is required for accessibility and is a ranking factor for image search. Every image should have a brief, descriptive alt text. Screen readers use alt text to describe images to visually impaired users.

2. Using original camera photos without resizing: A 20-megapixel camera photo can be 10+ MB. Resizing to 2000px wide and compressing to 80% quality reduces that to 200-500 KB with no visible quality loss on screens.

3. Forgetting focal points on feature images: Without a focal point, mobile crops might cut off the important part of the image. A portrait photo centered on a face works fine on desktop but the face might be cropped out on mobile.

4. Using the wrong image format: Screenshots with text should be PNG (sharp text). Photographs should be JPEG (smaller file size, good quality). Using JPEG for a screenshot with text results in blurry text; using PNG for a photograph results in unnecessarily large files.

5. Relying on hotlinked images: Embedding images from other servers (hotlinking) is unreliable. If the external server goes down or changes URLs, your images break. Always upload images to your own Ghost installation.

Practice Questions

1. What image sizes does Ghost automatically generate when you upload an image? Answer: Ghost generates five sizes: xs (300px), s (600px), m (1000px), l (1600px), and xl (2000px). You can request any size in your theme using the {{img_url}} helper with the size parameter.

2. How does the focal point feature work for feature images? Answer: When you set a focal point by clicking on the feature image, Ghost stores those coordinates. When rendering the image at different aspect ratios, Ghost crops around the focal point to ensure the important part stays visible.

3. What is the best way to add a video to a Ghost post? Answer: Use the Embed card to insert videos from YouTube, Vimeo, or other platforms. For self-hosted videos, use an HTML card with a <video> tag pointing to your hosted file. Ghost does not host video files.

4. Challenge: Create an image-heavy post in Ghost that demonstrates best practices. Use at least 3 Image cards with alt text and captions, one Gallery card with 4+ images, and a feature image with a correctly set focal point. Verify each image loads correctly in both the editor and the published post.

FAQ

Mini Project

Your task: Optimize an image-heavy Ghost site for performance.

1. Find 10 images from your computer or download free stock photos.
2. Before uploading, resize each image to a maximum width of 2000px and compress to 80% JPEG quality.
3. Create a photo essay post in Ghost with a feature image, 5 Image cards with captions and alt text, and a Gallery card with 4 images.
4. Upload the optimized images and note the file sizes.
5. Compare the file sizes before and after optimization.
6. Add descriptive alt text to every image.
7. Set a focal point on the feature image.

This exercise gives you a repeatable image workflow for professional Ghost content.

What's Next

Now that you understand image management, it is time to build custom themes:

Continue to Lesson 15: Theme Basics — Learn default.hbs, post.hbs, page.hbs, and theme partials.

Related lessons:

• Handlebars Templates — Ghost templating language
• Custom Themes — Build and upload custom themes