Compass

Adding Images

Keep article images next to their MDX files so Astro can optimize them and make them responsive.

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.

Placeholder illustration

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

That is why Compass keeps the Open Graph image in public/, but article screenshots belong in src/content/....

Write useful alt text

Alt text should explain what the reader gains from the image.

Better examples:

  • Alt="Billing settings panel with invoice history and plan selector"
  • Alt="Flowchart showing how MDX content moves from draft to published"

Less helpful examples:

  • Alt="Screenshot"
  • Alt="Image 1"

Suggested workflow

  1. Create the article folder inside the matching category-slug folder.
  2. Name the article file after the article slug, such as adding-images.mdx.
  3. Save screenshots and diagrams in that same folder.
  4. Use ![](./image-name.png) for straightforward content images.
  5. Switch to <Image /> when you need more control.
  6. Run npm run build or npm run check before publishing.

Team convention for Compass

  • every article uses its own folder with a slug-matched .mdx file
  • article-owned images go in src/content/... beside the article
  • stable public assets stay in public/
  • keep filenames short, descriptive, and lowercase with hyphens

Updated June 4, 2026