Images

Use images when they help readers inspect a real interface, compare states, or understand a workflow.

Blog images#

Keep blog images beside the post:

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

The example of image

Frontmatter#

Reference the image in frontmatter so cards, metadata, and article pages can use the same source.

---
title: Designing docs that scale
image:
  src: "./cover.jpg"
  alt: "Documentation workspace on a large display."
---

Image guidance#

Use this guidance when deciding whether an image improves the page.

• Use descriptive alt text.
• Prefer real product screenshots over generic visuals.
• Keep images close to the content that owns them.
• Avoid adding images that do not explain anything.

Review criteria#

Before publishing, check that images load, crop well on cards, and still make sense when viewed on smaller screens.

Image placement#

Place images close to the paragraph they support. Readers should not need to scroll back and forth to understand what the screenshot is explaining.

Before a workflow#

Use an image before a workflow when it gives readers context for the final result. This works well for interface tours and visual setup guides.

After a workflow#

Use an image after a workflow when readers need to verify that their result matches the expected state.

Accessibility notes#

Images should improve comprehension without becoming the only source of meaning. If an image contains important text, summarize that text in the surrounding prose.

Alt text pattern#

Write alt text that describes the useful information in the image, not every decorative detail. Keep it short enough to scan but specific enough to help.