Inline Images: Rules and Examples

An inline image is a single image placed inside the reading flow to clarify or prove the point immediately around it. It is not a gallery, promotional panel, or substitute for text. Ask what the reader can understand or verify after seeing it that nearby words do not provide as efficiently.

The keyed notch prevents the connector from entering the socket in the wrong orientation.

The rendered element above belongs immediately after a paragraph that tells the reader to check the connector orientation. The crop makes the notch visible, the caption states its significance, and the following instruction can continue without asking the reader to decode a large, unrelated scene.

Why this element matters

Readers alternate between scanning and focused inspection. A well-placed image turns an abstract description into a recognizable shape, shows evidence, or reduces the effort needed to imagine a visual state. Placement implies that it explains nearby text. When that relationship is weak, readers inspect it, find no additional meaning, and have to recover their place.

The relevant psychological principle is signaling. Crop, caption, and surrounding text direct attention toward the detail that matters. A photograph of an entire machine is weak when the sentence concerns a two-centimeter locking tab. A focused crop of that tab gives the reader one visual question to answer. The image does not need arrows or embedded prose when framing alone can make the subject obvious.

Machine extractability is the ability of software to identify a unit and preserve its relationship to nearby meaning. A semantic <figure> containing an <img> and optional <figcaption> gives crawlers, assistive technology, migration tools, and AI retrieval systems a stable unit. Alternative text states what the image contributes; dimensions describe its geometry; a caption exposes interpretation or provenance outside the pixels.

Machines must not need computer vision to recover an essential instruction, number, warning, or conclusion. If an image contains a decisive measurement or label, repeat that information in nearby text or use a structured table. The element writing rules control the shared directive syntax, source paths, body mapping, and precedence. This page takes precedence for inline-image fields, sizing, loading, caption, and alternative-text decisions.

When to use it

Use an inline image when one visual directly supports one nearby idea and the image remains useful at the reading column’s width. Appropriate jobs include showing a physical detail, identifying a place or object, presenting a simple before-or-after state, giving visual proof of a tested condition, or demonstrating the appearance of an output that does not require annotations.

Run three tests before adding it:

1. Contribution test: Name the new information, evidence, or recognition the image supplies.
2. Context test: Identify the exact paragraph the image supports. If three sections could claim it equally, its purpose is probably too broad.
3. Removal test: Hide the image. If nothing meaningful is lost, mark it decorative only when the design genuinely needs it; otherwise remove it.

Near-miss cases cause most misuse. Use an annotated screenshot when readers must locate controls or match several numbered regions. Use a diagram when the content is a relationship, sequence, or system rather than a visible object. Use a gallery when multiple peer images must be browsed. Use a comparison table when differences depend on repeated criteria. Use an imagebox when an image and a substantial explanation form a self-contained two-column unit.

Do not insert a generic stock photograph merely to break up text. A handshake does not prove a partnership; a laptop does not explain software; a light bulb does not make an idea clearer. Do not publish text as an image to preserve typography. Do not use a screenshot for prose, a chart without readable values, or an image whose license and provenance are unknown.

Ready to Monitor Your AI Visibility?

Track how AI chatbots mention your brand across ChatGPT, Perplexity, and other platforms.

Get Started Contact

Where to place it

Place the image immediately after the paragraph that introduces what the reader should inspect. The reason comes first so the reader knows where to direct attention. Follow the figure with interpretation only when the image is evidence whose consequence is not obvious. In a procedure, place it after the relevant action and before the success check; never split a sentence from its qualification or an instruction from its warning.

An inline image may sit below an H2 only when the heading and first paragraph establish its purpose. Keep the figure, caption, and credit together across responsive layouts and page breaks.

Do not place it inside a paragraph, list item, table cell, callout, accordion, clickable card, or another media element. Do not put two inline images back to back: combine true peers into a gallery, or add the explanation that distinguishes their jobs. It may not sit beside a dense table, video, chart, or call to action where both objects compete for attention. Keep at least one meaningful paragraph between separate media units unless they form one explicitly defined comparison.

Use normal content width by default and a narrower presentation for a small object or portrait. Use an approved wide-media container only when detail cannot be read otherwise; never create page-level horizontal scrolling.

Anatomy

1. Figure boundary: Groups the asset, caption, and credit as one unit in the document flow.
2. Image source: Resolves to an approved, existing asset rather than a remote hotlink or placeholder.
3. Alternative text: Replaces the image’s contextual function for readers who cannot perceive it; it is empty only for decoration.
4. Intrinsic dimensions: Reserve the correct aspect ratio before the file arrives and prevent layout movement.
5. Responsive candidates: Let the browser choose an appropriately sized file rather than downloading the largest source everywhere.
6. Rendered size: Keeps the relevant detail legible without overflowing or upscaling a weak source.
7. Caption: Adds interpretation, identification, date, scale, or provenance when that information helps every reader.
8. Credit: Records creator and source when licensing or editorial policy requires it.

The image filename and alt text are not interchangeable. A stable filename helps asset maintenance; contextual alt text explains the image’s purpose in this occurrence. The same photograph may therefore have different alt text when it supports different points, although reusing one image for unrelated points is a warning sign.

Stay Updated on AI Visibility Trends

Get the latest insights on AI mentions, brand monitoring, and optimization strategies.

Email address

Subscribe

Design examples

The element supports three semantic variants and two width treatments. Loading behavior is not a visual variant.

Informative image, content width

This is the default. The image contributes recognizable detail or evidence, uses nonempty alt text, and stays within the reading container.

Informative image, wide media

Use the approved wide container only when a map, detailed photograph, or legible output needs more horizontal space. The surrounding text still owns the meaning, and mobile presentation must remain usable.

Decorative image

Decoration carries no unique information, uses alt="", has no explanatory caption, and should be rare in long-form production content. It must not be the only expression of mood, status, identity, or outcome.

Detail image with optional expansion

Use expansion only when the normal inline rendition establishes context but fine detail requires a larger view. The image itself remains understandable without activating the link, and the control’s accessible name describes the action.

Narrow viewport behavior

Every variant scales down within the viewport, preserves aspect ratio, and keeps the caption attached. If meaningful text becomes unreadable, provide a mobile crop or replace the image with structured text; forcing pinch-to-zoom is not the default solution.

Parameters

The contract stores editorial and delivery decisions. Borders, shadows, spacing, and breakpoint values belong to the renderer.

The directive has no title field: an inline image belongs to the surrounding section rather than creating a new section. Its first body paragraph maps to caption; no first heading is accepted. Credit comes from trusted asset metadata when available, preventing authors from silently changing license information.

Syntax and code examples

The following three notations map the same source, alternative text, intrinsic dimensions, size, caption, and loading intent. Example asset paths demonstrate the contract only; production source must resolve to an existing file.

Portable Markdown directive

:::inline-image{src="/cdn-assets/seo-playbook/examples/keyed-connector.webp" alt="Connector close-up showing the keyed notch aligned with the matching socket ridge" width=1600 height=1000 size=content loading=lazy}
The keyed notch allows insertion in only one orientation.
:::

The first paragraph is the caption. Additional paragraphs, headings, lists, buttons, and nested media are rejected because they would turn a focused figure into a general content container.

Hugo shortcode

{{< inline-image src="/cdn-assets/seo-playbook/examples/keyed-connector.webp" alt="Connector close-up showing the keyed notch aligned with the matching socket ridge" width="1600" height="1000" size="content" loading="lazy" >}}
The keyed notch allows insertion in only one orientation.
{{< /inline-image >}}

Named parameters are used exclusively. This is a portable adapter specification, not a claim that a local shortcode is registered. Until the adapter exists, use the publishing system’s established semantic figure implementation; never add a broken shortcode call to production content.

WordPress block

<!-- wp:image {"id":412,"width":"auto","height":"auto","sizeSlug":"large","linkDestination":"none"} -->
<figure class="wp-block-image size-large">
  <img src="/cdn-assets/seo-playbook/examples/keyed-connector.webp"
       alt="Connector close-up showing the keyed notch aligned with the matching socket ridge"
       width="1600" height="1000" loading="lazy">
  <figcaption class="wp-element-caption">The keyed notch allows insertion in only one orientation.</figcaption>
</figure>
<!-- /wp:image -->

Use media-library metadata but review contextual alt text for this placement. Do not link to the attachment page by default.

Examples

Good: a focused image answers the visual question

An installation guide says: “Before applying power, align the keyed notch with the socket ridge; forcing the connector can bend the pins.” It then places this figure:

The notch and ridge align before the locking tab can engage.

This works because the image arrives after the reason to inspect it, the crop contains both matching features, and the caption explains the relationship rather than saying “connector image.” The instruction and consequence remain in text. Intrinsic dimensions prevent movement while loading, and the image can be lazy-loaded because it appears well below the first viewport.

Bad: decoration interrupts without explaining

An article about configuring analytics inserts a full-width stock photograph of a person looking at colorful charts between a step and its warning. Its alt text says “analytics dashboard SEO optimization reporting data,” the source is 5000 pixels wide, no dimensions are declared, and the file loads eagerly halfway down the page.

The image is bad because it proves no configuration state, separates a risky action from its warning, stuffs keywords into alt text, downloads more pixels than the layout can use, and may shift the warning when its height becomes known. Remove it. If the real interface contains an ambiguous control, replace it with a focused, current screenshot and keep the warning attached to the action.

Schema markup and accessibility

An inline image creates no special schema entity by default. A meaningful image may supply the image property of Article, HowTo, Product, Review, or another appropriate entity. Use ImageObject only with a stable contentUrl and truthful available metadata such as caption, dimensions, creator, and license. Do not mark up decoration or unverified rights.

Good alt text describes function in context, not every visible object. Ask what sentence would replace the image if it failed to load. “Connector close-up showing the keyed notch aligned with the matching socket ridge” is useful in an installation guide. “A black and silver object on a gray background” is visually literal but functionally weak. Avoid “image of” and “photo of” unless the medium itself matters, such as distinguishing a photograph from a simulation.

Every <img> needs an alt attribute. Use nonempty text for informative images and alt="" for decoration. Omitting the attribute is not equivalent: some screen readers announce the filename. Do not put essential prose, instructions, citations, or long data series inside pixels. If visible text in the image matters, repeat it in the surrounding content.

Use <figure> and <figcaption> when a caption belongs to the image. Do not add a figure role manually. An expandable image needs a visible, keyboard-operable control with a descriptive name, predictable focus movement, Escape support when it opens a modal, and access to the same alt text and caption at the enlarged size. Do not wrap every image in an unlabeled link to the source file.

Responsive delivery is part of image SEO and accessibility because it makes content available without unnecessary delay. Use srcset and sizes or an equivalent image pipeline so responsive design can select a suitable candidate. Preserve aspect ratio, set intrinsic width and height, and constrain the rendered maximum width to its container. These dimensions reserve space and reduce Cumulative Layout Shift , the movement of page content while resources load.

Lazy loading defers an off-screen resource until the reader approaches it. Use loading="lazy" for images below the initial viewport. Do not lazy-load an image likely to appear immediately, because the delay can make the largest visible content arrive later. Use eager loading and fetchpriority="high" only when measurement and template position identify the image as a probable primary above-fold asset; multiple high-priority images defeat the signal.

Writing rules

The writing around an inline image does most of the interpretive work, so brevity in the element does not mean vagueness.

• Introduce the reason before the figure in one nearby paragraph. Do not use coordinate language such as “below” when responsive or syndicated layouts may move the asset.
• Write informative alt text for the image’s function in this exact context. Target 40–160 characters; use up to 250 only when complexity genuinely requires it.
• Keep captions to 5–30 words and one sentence when possible. Identify, interpret, date, scale, or credit the image; do not merely repeat the alt text.
• Show one primary subject or relationship. If the reader must inspect more than three independent areas, use an annotated screenshot, diagram, table, or gallery.
• Use American spelling, plain language, and the same terminology as the surrounding section. Alternative text is not a keyword field.
• Keep all essential instructions, warnings, measurements, prices, dates, and conclusions in HTML text, even when they also appear in the pixels.
• Never place headings, multiple paragraphs, lists, tables, buttons, forms, video, audio, or another image inside the element body.
• Never use an empty caption to create spacing, an invented credit, a remote hotlink, an unlicensed asset, customer data without permission, or a nonexistent placeholder path.
• Never stretch, distort, or upscale an image to fill a design slot. Crop only when the crop preserves the evidence and context the text discusses.

Post types that use it

The postTypes array in frontmatter is the canonical join. A post type may narrow the requirement, but it does not change the element’s field or accessibility contract.

QA checklist

• Purpose: The reviewer can state the unique information, evidence, or recognition the image adds.
• Placement: The preceding paragraph establishes what to inspect, and no warning, qualification, or citation has been separated from its claim.
• Correct element: A single inline image is more appropriate than an annotated screenshot, gallery, diagram, table, or imagebox.
• Asset validity: The source exists, uses an approved format and root-relative path, and has verified rights and provenance.
• Privacy: The image contains no unapproved customer data, names, email addresses, tokens, browser details, or location clues.
• Crop and quality: The subject remains legible at rendered and mobile widths without distortion, avoidable empty space, or destructive compression.
• Alternative text: The alt attribute is present and either contextually informative or intentionally empty for decoration; it is not a filename, caption duplicate, or keyword list.
• Caption: When present, it adds identification, interpretation, date, scale, or provenance in 5–30 words.
• Dimensions: Intrinsic width and height match the source ratio and reserve stable layout space.
• Responsive delivery: Candidate sizes match realistic display widths; the largest source is not sent to every viewport by default.
• Loading: Below-fold images are lazy-loaded; initially visible images are not; high fetch priority is limited to a measured primary candidate.
• Mobile behavior: The image fits without page-level horizontal scrolling, and its meaningful detail remains readable without forced zoom.
• Text fallback: Essential instructions, warnings, measurements, and conclusions exist in page text rather than only in pixels.
• Structured data: Any schema properties are accurate, supported by visible content, and omitted for decoration.
• Portable parity: Markdown, Hugo, and WordPress preserve the same source, alt text, dimensions, caption, credit, and loading intent.
• Pending captures: No nonexistent path renders; each requested example remains a SCREENSHOT comment while screenshotsPending = true.

FAQ

The academy template renders the five reviewed questions stored in this page’s [[faq]] frontmatter. They cover alternative text, lazy loading, captions, sizing, and the decision to remove an image that adds nothing.