Use images without breaking the reading flow

An image earns its place in documentation when it explains a state, sequence, relationship, or result faster than prose. Its presentation should follow that job. A screenshot that supports one sentence needs a different treatment from a diagram readers must inspect closely.

Ginko Docs renders ordinary Markdown images through Nuxt Image and can add click-to-zoom behavior. The figure component adds explicit dimensions, a caption, aspect-ratio control, and optional bleed without requiring a page-specific Vue template.

Use Markdown for an image in the reading flow

Use standard image syntax when the surrounding paragraph already supplies the context and the image does not need a caption.

Write alt text for the information a reader needs from the image. Do not repeat “image of” or use the filename. If the image is decorative and carries no information, use empty alt text rather than inventing a description.

Use a figure for a caption and stable geometry

Add a figure when the caption contributes meaning or when you need explicit dimensions to prevent layout shift.

The width and height props describe the source image. They let the browser reserve the correct space before the file loads. The aspect and fit props control presentation; they should not compensate for an incorrectly cropped source asset.

Reserve bleed for important detail

A wider figure can help with dense diagrams, comparison screenshots, or editorial photography that loses useful detail inside the text measure.

Do not use bleed as decoration on every page. Repeated width changes interrupt scanning and make ordinary screenshots look more important than the instructions around them.

Keep text and media in sync

Place an image after the sentence that introduces it. Explain the conclusion in text as well; a screenshot should not be the only place a required value or error message appears. Update screenshots when labels, routes, or defaults change.

For zoomable images, make sure the reduced view still exposes the main subject and the original asset is sharp enough to inspect. A larger blurred screenshot does not become more useful when opened in a dialog.

The final asset should have a stable public path, meaningful alt text, intrinsic dimensions when using figure, and a caption only when the caption adds information not already present in the paragraph.