Adding Images

Compass works best when article images live inside src/, next to the article that uses them. That gives Astro the chance to optimize local files during the build, generate responsive output, and keep each article’s assets organized in one place.

Recommended article structure

Compass uses one folder per article. Keep article-specific images in that same folder instead of public/:

src/content/docs/compass-docs/adding-images/
|-- adding-images.mdx
`-- docs-image-placeholder.png

This pattern scales well for screenshots, diagrams, and step-by-step walkthroughs because the content and its assets stay together.

Use Markdown for the simple case

When an image belongs to the article and lives next to the file, standard Markdown is enough:

![Placeholder illustration](./docs-image-placeholder.png)

With Compass’s Astro config, local images in src/ are optimized automatically and use responsive image behavior by default.

Use Astro’s Image component when you need more control

If you want explicit sizing, priority loading, or a different layout mode, import the asset and render it with astro:assets:

import { Image } from 'astro:assets';
import diagram from './system-diagram.png';

<Image 
  src={diagram} 
  alt="System diagram showing request flow through Compass" 
  width={1200} 
  layout="constrained" 
/>

When to use public/

Use public/ only when an asset needs a stable direct URL and should not be processed by Astro.

Good examples:

• favicons
• social preview images
• files you want to link to directly by URL
• assets shared outside the article rendering flow