Images

Add responsive, accessible images that readers can inspect in a focused lightbox.

Usage

Add an image with standard Markdown syntax. Images are displayed in a framed container and open in a larger preview when selected.

Analytics dashboard showing revenue, active customers, and recent transactions.

![Analytics dashboard showing revenue, active customers, and recent transactions.](/image-example.jpg)

The text inside the square brackets becomes the image's alternative text and its visible caption. Write it for the information the reader needs, not for every decorative detail in the image.

Captions

Use a title when the visible caption should provide context beyond the alternative text. The alt text still describes the image for readers who cannot see it.

![Settings page with the API access panel open.](/images/api-settings.jpg "Create a token from Settings → API access.")

Keep captions concise. If an explanation requires multiple sentences, place it in the surrounding article instead.

Local images

Store shared documentation images in public, then reference them from the root URL.

public/
  images/
    api-settings.jpg
    deployment-ready.png

![API access settings with a generated token.](/images/api-settings.jpg)

Keeping related screenshots in a dedicated folder makes them easier to replace when the interface changes.

Place images with intent

Use images when they help readers identify an interface, compare states, or verify the result of a workflow.

Before a workflow

Place an image before the instructions when readers need to recognize the screen or understand the destination before they begin.

After a workflow

Place an image after the instructions when readers need to compare their result with a known successful state.

Do not use a screenshot as the only place where a setting name, command, or required value appears. Repeat essential information in the surrounding text.

Alternative text

Alternative text should replace the useful meaning of the image when the image is unavailable.

Image	Weak	Better
Deployment result	`Screenshot`	`Deployment details showing a Ready status.`
Settings panel	`API settings page`	`API settings with token scope set to Read and write.`
Decorative divider	`Blue gradient divider`	Use an empty alt value: `![](...)`

Avoid phrases such as “image of” or “screenshot of.” Screen readers already announce that the element is an image.

Image quality

Capture screenshots at a high enough resolution to keep interface text sharp.
Crop unused browser chrome and empty space before adding the asset.
Use a consistent viewport size across screenshots in the same guide.
Prefer PNG for interface screenshots and JPEG or WebP for photography.
Remove private customer data, tokens, email addresses, and internal URLs.
Check both light and dark themes when screenshots include transparent areas.

Blog cover images

Keep each cover image beside the post that owns it. This makes the article portable and prevents unrelated assets from collecting in one shared folder.

src/content/blog/
  designing-docs-that-scale/
    index.mdx
    cover.jpg

Reference the cover in frontmatter so the blog card, social metadata, and article page use the same source.

---
title: Designing docs that scale
description: Build a content structure that remains useful as the product grows.
image:
  src: "./cover.jpg"
  alt: "Documentation workspace with the navigation structure expanded."
---

Before publishing

Check every image at desktop and mobile widths. Confirm that it loads, remains readable, opens in the preview, and still makes sense beside the current instructions.