Images and media inside MDX

Images are one of the easiest ways to make a fast site slow. Our MDX standard treats media as a deliberate part of the page, not decoration added at the end.

Use images when they add information

Technical documentation often does not need a hero image at all. A screenshot, diagram, or project image should help explain the subject.

Keep file sizes under control

Large source images should be resized and compressed before they become part of the site. Modern formats such as WebP or AVIF are useful when they fit the pipeline.

Dimensions matter

Known image dimensions help prevent layout shift. For images rendered through Next.js, dimensions and responsive sizing rules should be explicit.

Do not load everything eagerly

Only the image that meaningfully affects the initial viewport should be considered for priority loading. Everything else should load when needed.

Alt text should be useful

Alt text should describe the image's relevant content. Decorative images can be treated as decorative. We do not stuff keywords into alt text.

Repository images are preferred for durable content

For long-lived documentation and portfolio content, keeping approved assets with the project improves reliability and avoids depending on third-party URLs that may disappear or change.

Content images pass through a controlled resolution layer

In one of our content-heavy service sites, MDX does not need to know whether an image is a static import, a public path, or a remote value. A small resolver checks approved registered images first, accepts deliberate root-relative or remote paths, and converts bare filenames into a controlled public content path.

That gives writers a simpler content format while the application keeps responsibility for how the asset is actually served. Another location system uses an explicit image registry. The content file references a key, the loader maps that key to a statically imported asset, and the component receives a real image object with known dimensions. This is especially useful for important repeated imagery where we want build-time guarantees.

Media belongs to the content model when it changes meaning

A hero image, project image, or instructional screenshot can be part of the document's meaning. Those assets should be referenced deliberately in the content model. Decorative textures, gradients, and interface icons usually belong in the component or stylesheet instead. That distinction keeps the MDX file focused on editorial decisions rather than implementation decoration.

We separate source quality from delivery quality

A beautiful source image can still be a terrible web asset if it is enormous. A highly compressed image can be technically small and visually useless. We optimize for both. The application controls responsive rendering, dimensions, and loading. The source asset should still be cropped and sized with its role in mind. A card thumbnail and a full project gallery do not need the same source dimensions.

Alt text is written for the reason the image is present

If the image is showing a finished installation, the alt text should describe the relevant result. If it is purely decorative, empty alt text may be more appropriate. If it is a diagram, the text should capture the information a reader would otherwise miss.

We do not use alt text as a hidden keyword field.

Media errors should fail visibly during development

Static imports are valuable partly because a missing asset can break the build rather than quietly shipping a broken URL. For public-path content, validation can check whether referenced files exist. The connectrader post-build audit also scans source references for missing images. The larger standard is simple: editorial flexibility should not mean asset behavior becomes untraceable.