Web Development / SEO

Image SEO for Developers

A developer-focused guide to image SEO: alt text, filenames, metadata, structured data, crawlable markup, responsive images, and performance-aware delivery.

This article is part of the BadGames article-image SEO cluster. The page treatment highlights the image decision that matters most for this specific topic.

featuredclean article hero image

socialpreview image when needed

scansupporting visuals where useful

Key Takeaways

Use the right image for the job. The article image should support the reader’s decision instead of acting as decoration.

Keep the page scannable. Inline assets should break up the article only where they make the topic easier to understand.

Publish the metadata. Featured images, social images, alt text, and preview metadata need to agree with the article.

Image SEO is not about tricking Google with keyword-stuffed file names or magical alt text.

It is about making images understandable.

A good article image should be useful to readers, accessible to people who cannot see it, crawlable by search engines, connected to the page topic, and described with clean metadata. When those basics are in place, Google and other platforms have a much better chance of understanding what the image is, why it matters, and how it relates to the article.

For the design side of article images, start with our guide to featured image best practices for articles. For dimensions and crop decisions, see our guide to WordPress featured image size.

This article focuses on the technical SEO layer.

Category Web Development

Tags Performance SEO

Image SEO starts with the page

An image does not rank or appear in isolation. Google looks at the image, but it also looks at the page around the image.

Google’s image SEO documentation says Google uses page content, captions, image titles, filenames, alt text, and other signals to understand images. Google also recommends placing images near relevant text and on pages that are relevant to the image subject. Google image SEO best practices

That means the best image SEO usually starts before we write any metadata.

Ask:

Is this image relevant to the article?
Is it placed near the section it supports?
Does the surrounding text explain the same topic?
Is the page title and meta description aligned with the image?
Is the image useful, or is it just decoration?

A strong image on a weak or unrelated page will not do much. A relevant image inside a clear article is much easier for both readers and search engines to understand.

Use real image elements for important images

If an image is important content, use real HTML image markup.

Google says it can find images in the src attribute of an HTML img element, including images inside a picture element. Google also says it does not index CSS background images. Google image SEO best practices

That gives us a simple rule:

Use CSS background images for decoration. Use real image elements for content.

Good for a main article image:

<img
  src="/images/featured-image-seo-guide.webp"
  width="1600"
  height="900"
  alt="Article preview image showing image SEO elements such as filename, alt text, metadata, and structured data."
>

Not ideal for a main content image:

<div class="hero-image"></div>

CSS background images are fine for visual decoration, gradients, patterns, and layout effects. But if the image represents the article, explains a concept, or is meant to be indexed, use an actual image element.

Social Preview

Social shares need the image SEO promise in plain language.

The social preview keeps the technical topic readable by focusing on crawlable files, useful alt text, filenames, and metadata that agree with the page.

Social preview image for Image SEO for Developers. — Use this card when the article is shared; the in-page featured image can stay cleaner and less text-heavy.

Use descriptive filenames

A filename is a small signal, but it is still part of the image context.

A weak filename says nothing:

IMG_2849.jpg

screenshot-final-new-2.png

image.webp

A better filename describes the image:

wordpress-featured-image-size-1600x900.webp

google-discover-article-image-preview.webp

image-seo-alt-text-filename-structured-data.webp

The filename should be readable and specific. It does not need to be stuffed with every keyword from the article.

Good filename rules:

use lowercase letters
use hyphens between words
describe the image subject
keep it short enough to read
avoid random exports like final-v7-new-new.webp
avoid keyword stuffing

Bad:

best-image-seo-wordpress-google-discover-alt-text-filename-structured-data-social-preview-featured-image-guide.webp

Better:

image-seo-alt-text-structured-data.webp

The better filename is still descriptive, but it does not look spammy.

Write alt text for people first

Alt text is one of the most misunderstood parts of image SEO.

It is not mainly a keyword field. It is a text alternative for people who cannot see the image. It can also help search engines understand the image, but the first purpose is accessibility.

The W3C explains that informative images should have text alternatives that convey the meaning or content of the image, and that the right alt text depends on why the image is used. W3C informative images tutorial

Google also recommends writing useful alt text and warns against keyword stuffing. Google image SEO best practices

Bad alt text:

alt="image seo wordpress google discover featured image alt text filename structured data"

Better alt text:

alt="Diagram showing how image SEO connects filenames, alt text, Open Graph metadata, and structured data."

The better version describes what the image communicates.

Alt text depends on context

The same image can need different alt text depending on where it appears.

Example: a screenshot of a WordPress featured image panel.

In an article about WordPress publishing workflow:

alt="WordPress editor showing the featured image panel for an article."

In an article about image SEO:

alt="WordPress featured image panel used to select the image that appears in article previews."

In an article where the screenshot is only decorative:

alt=""

The image pixels are the same. The purpose is different.

That is why auto-generated alt text often needs human review. It may describe the image literally, but miss why the image is included in the article.

When to use empty alt text

Not every image needs descriptive alt text.

If an image is purely decorative and adds no information, empty alt text is usually the right choice:

alt=""

Examples:

background texture
decorative divider
abstract shape
repeated icon that adds no meaning
visual ornament already explained by nearby text

But article featured images are usually not decorative. They represent the article. So they usually deserve short, useful alt text.

A practical rule:

If removing the image would remove meaning, write alt text. If the image is only decoration, use empty alt text.

The W3C alt decision tree is useful for deciding what kind of text alternative an image needs. W3C alt decision tree

Put images near relevant text

Search engines use the surrounding page to understand images.

So do readers.

If an image explains a section, place it near that section. If a screenshot shows an example, introduce it before or after the image. If an image is the article’s featured image, make sure the article title, intro, and metadata all support the same topic.

Weak placement:

An image about Open Graph metadata appears inside a section about image compression.

Better placement:

An Open Graph image example appears inside the section that explains `og:image`, `og:image:width`, `og:image:height`, and `og:image:alt`.

This sounds obvious, but it matters. A good image in the wrong section becomes confusing.

Scan-Friendly Summary

An image SEO checklist for developers.

The summary graphic condenses implementation checks: file access, descriptive names, alt text, structured data, dimensions, and internal image context.

Infographic summary for Image SEO for Developers. — The infographic is a developer-facing preflight for image markup and crawlability.

Use captions when they help

Captions are not required for every image. But when an image needs explanation, a caption can help both readers and search engines.

Good use cases for captions:

charts
diagrams
screenshots
comparisons
before/after images
process images
images with important context
images where the source needs attribution

Example:

Screenshot of a WordPress article where the featured image is used as the default Open Graph image.

A caption should not repeat the alt text word for word. Alt text is for the text alternative. A caption is visible explanatory text for all readers.

Make images crawlable and indexable

For image SEO, the image URL needs to be accessible.

Check that:

the image URL returns a normal 200 response
the image is not blocked by robots.txt
the image is not behind a login
the page itself is indexable
the image is not only loaded from a temporary tool URL
the image URL in metadata is the final public URL
the image is not served with broken hotlink protection
the image is not accidentally noindexed through headers or rules

Google’s structured data guidelines say that image URLs used in structured data must be crawlable and indexable. Otherwise, Google Search cannot find and display them in search results. Google structured data guidelines

This is especially important when using generated images, temporary preview images, local staging URLs, private CDNs, or media files copied between environments.

The final article should point to the final public image.

Use Open Graph metadata for the preferred preview image

If we want platforms to use a specific image, we should say so.

Open Graph metadata lets a page define the title, description, URL, and image used when the page is shared. The Open Graph protocol includes image properties such as og:image, og:image:width, og:image:height, and og:image:alt. Open Graph protocol

Example:

<meta property="og:type" content="article">
<meta property="og:title" content="Image SEO for Developers">
<meta property="og:description" content="How to make article images understandable with alt text, filenames, metadata, structured data, and crawlable image URLs.">
<meta property="og:url" content="https://example.com/image-seo-for-developers/">
<meta property="og:image" content="https://example.com/images/image-seo-for-developers-1600x900.webp">
<meta property="og:image:width" content="1600">
<meta property="og:image:height" content="900">
<meta property="og:image:alt" content="Diagram showing how image SEO connects filenames, alt text, metadata, and structured data.">

For most WordPress articles, the featured image can be the default Open Graph image. For important pages, it can be worth creating a separate social preview crop.

Use Article structured data for article images

For article pages, Google supports Article, NewsArticle, and BlogPosting structured data. Google says Article structured data can help Google understand more about the page and show better title text, images, and date information in Google Search and other surfaces. Google Article structured data

A simple BlogPosting image setup can include multiple image crops:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Image SEO for Developers",
  "image": [
    "https://example.com/images/image-seo-for-developers-1x1.webp",
    "https://example.com/images/image-seo-for-developers-4x3.webp",
    "https://example.com/images/image-seo-for-developers-16x9.webp"
  ],
  "datePublished": "2026-06-27T09:00:00+02:00",
  "dateModified": "2026-06-27T09:00:00+02:00",
  "author": {
    "@type": "Organization",
    "name": "Bad Games AB"
  }
}
</script>

Google’s Article structured data documentation recommends multiple high-resolution images in aspect ratios such as 16:9, 4:3, and 1:1. Google Article structured data

We do not need to manually write JSON-LD for every post if our WordPress system handles it. But we should know what the system outputs and test important pages.

Avoid structured data image mistakes

Common mistakes:

using a logo as the article image
using an unrelated generic image
using a staging image URL
using an image blocked by robots.txt
using a private image URL
using an image that returns 404
using a tiny thumbnail instead of a high-resolution image
using structured data that does not match the page content

Google’s structured data guidelines say images specified in structured data must be relevant to the page and that image URLs must be crawlable and indexable. Google structured data guidelines

A structured data image should be the image we actually want associated with the article.

Use image sitemaps when they are useful

Most small WordPress sites do not need a complicated custom image sitemap on day one.

But image sitemaps can help Google discover images, especially if images are loaded in ways that are harder to discover or if a site has many important images. Google documents image sitemaps as a way to help Google discover images on a site. Google image sitemaps

For a normal article site, priorities usually come first:

Use real image elements.
Use crawlable image URLs.
Use descriptive filenames and alt text.
Use Open Graph metadata.
Use Article structured data where appropriate.
Make sure the XML sitemap and media handling are sane.
Consider image sitemaps if there is a real discovery problem.

Do not start with an image sitemap if the basic image markup is broken.

Keep image URLs stable

Changing image URLs can break previews, metadata, caches, and search associations.

Try to avoid:

replacing images with new random filenames
using temporary upload paths
using staging domain image URLs
deleting old images without redirects
changing the og:image URL repeatedly for the same article
hotlinking images from external tools

Better:

upload final assets to the site
use descriptive stable filenames
keep the same URL unless the image really changes
update metadata when the image changes
test important URLs after publishing

Stability helps platforms cache and understand the page.

Optimize file size without destroying quality

Image SEO is not only about metadata. Performance matters too.

A huge image can slow down the article, especially if it is the main above-the-fold image. Featured images are often candidates for Largest Contentful Paint. web.dev recommends making the LCP resource discoverable early and not lazy-loading the LCP image. web.dev LCP optimization

Practical image delivery rules:

export WebP or optimized JPEG
use responsive image sizes
set width and height
do not lazy-load the main above-the-fold featured image
lazy-load below-the-fold images
avoid uploading huge uncompressed images
avoid visual noise that compresses badly
test the page on mobile

A practical responsive image example:

<img
  src="/images/image-seo-for-developers-1200.webp"
  srcset="/images/image-seo-for-developers-800.webp 800w,
          /images/image-seo-for-developers-1200.webp 1200w,
          /images/image-seo-for-developers-1600.webp 1600w"
  sizes="(max-width: 800px) 100vw, 1200px"
  width="1600"
  height="900"
  fetchpriority="high"
  alt="Diagram showing how image SEO connects filenames, alt text, metadata, and structured data."
>

A good image should be large enough to look good, but not heavier than it needs to be.

Test the rendered page, not just the editor

Do not assume the WordPress editor view tells the whole story.

After publishing, check the actual page source or rendered HTML.

Check:

the featured image appears
the image has useful alt text
width and height are present
the image URL is public
og:image is present
og:image:width and og:image:height are present
og:image:alt is present
Article or BlogPosting structured data includes the right image
the image URLs are not staging URLs
the page allows large image previews where appropriate
the main featured image is not lazy-loaded if it is above the fold

Tools that can help:

browser dev tools
Google Search Console URL Inspection
Rich Results Test
social sharing/debugging tools
direct image URL checks

The real output matters more than the admin settings.

A practical image SEO checklist

Before publishing an important article, check:

Is the image relevant to the article?
Is it specific, not generic?
Is it placed near relevant text?
Is the filename descriptive?
Is the alt text useful and not keyword-stuffed?
Is the image public and crawlable?
Is the image used with a real `img` or `picture` element?
Is the image not only a CSS background?
Is the image compressed?
Are responsive sizes available?
Are width and height set?
Is the main above-the-fold image not lazy-loaded?
Is `og:image` set?
Are `og:image:width`, `og:image:height`, and `og:image:alt` set?
Does Article or BlogPosting structured data use the right image?
Are structured data image URLs crawlable and indexable?
Is the image URL stable?
Do we have rights to use the image?

This checklist is boring in the best way. It catches the real problems.

Common image SEO mistakes

Keyword-stuffed alt text

Alt text should describe the image’s purpose. It should not be a pile of keywords.

Generic filenames

image-1.webp is not helpful. Use filenames that describe the image.

Important images as CSS backgrounds

CSS backgrounds are fine for decoration, but not for important article images.

Broken metadata

If og:image points to an old, missing, private, or tiny image, platforms may show the wrong preview.

Structured data using the wrong image

Do not use logos, placeholders, or unrelated images as the Article image.

Huge uncompressed featured images

High quality does not mean enormous file size.

Staging URLs in production

Never let local, staging, or temporary image URLs become the canonical article image.

Official references

For more detail, these are the main resources worth reading:

Final thought

Image SEO is not one trick.

It is a set of small, reliable publishing habits:

Use relevant images.
Use real image markup.
Use descriptive filenames.
Write useful alt text.
Keep images crawlable.
Use metadata.
Use structured data where appropriate.
Keep files fast.
Test the final page.

When those habits are in place, images become easier for users, platforms, and search engines to understand.

That is the goal.

Not keyword stuffing. Not metadata theater. Not random decoration.

Useful images, published cleanly.