Skip to content
Starlight

Asset Placement

Astro supports two useful strategies:

  • Processed source assets live under src/ (or beside content) and are imported into MDX. Astro fingerprints them, reads metadata, and can optimize supported raster images. The diagram on the image page lives in src/assets/diagram.svg.
  • Public assets live under public/ and are copied unchanged. This sample’s public/assets/starlight-demo.svg is available at the configured site base and is appropriate when a stable filename matters.
Starlight public asset copied without transformation

With a GitHub Pages base path, avoid bare host-root URLs such as /assets/file.svg. Use an imported asset, a relative URL, or prepend Astro’s BASE_URL so development and deployment resolve the same file.

See the live Image Optimization example.