Astro Starlight Asset Management Tutorial

What You Are Learning

This tutorial explains how to manage assets in an Astro Starlight site. Assets include images, maps, screenshots, PDFs, SVG diagrams, downloadable documents, icons, audio, and video.

public/ stores files copied directly into the final site.
src/assets/ stores files imported and processed by Astro.
Markdown and MDX pages can reference assets in different ways.
Deployment problems often come from broken paths or case mismatches.

The Big Picture

Asset file
  ↓
Choose where it belongs
  ↓
Reference it correctly
  ↓
Test in development
  ↓
Build and preview
  ↓
Deploy

Most asset problems come from placing files in the wrong folder or using a path that only works on your local computer.

Two Main Asset Locations

Folder	Best For	How You Reference It
`public/`	Static files, downloads, favicons, PDFs, and files that need direct URLs.	Use root paths like `/images/map.png`.
`src/assets/`	Images imported into Astro components, optimized images, and source-managed logos.	Import the asset or use Astro-supported paths.

Using the public Folder

The public/ folder is copied directly into the final site. If you place a file here:

public/images/world-map.png

You reference it like this:

![World Map](/images/world-map.png)

The word public does not appear in the URL.

Good public Folder Structure

public/
  favicon.png
  images/
    maps/
      world-map.png
      city-map.png
    screenshots/
      install-step-1.png
      deploy-settings.png
    diagrams/
      architecture.svg
      relationship-chart.svg
    characters/
      example-character.png
  downloads/
    world-bible-template.pdf
    lesson-checklist.pdf
    printable-character-sheet.pdf

Referencing Images in Markdown

![Deployment settings screenshot](/images/screenshots/deploy-settings.png)

Use descriptive alt text:

Good:
![Vercel deployment settings showing npm run build and dist output directory](/images/screenshots/vercel-settings.png)

Weak:
![image](/images/screenshots/vercel-settings.png)

Referencing Downloads

If you place a PDF in:

public/downloads/world-bible-template.pdf

Link to it like this:

[Download the World Bible Template](/downloads/world-bible-template.pdf)

Using src/assets

The src/assets/ folder is for assets that are part of your source code and may be imported by Astro components.

src/assets/
  logo.png
  hero-image.png
  icons/
    book.svg
    map.svg

Example Astro component import:

---
import logo from '../assets/logo.png';
---

<img src={logo.src} alt="Site logo">

Which Folder Should You Use?

Need	Use
A PDF download	`public/downloads/`
A simple image in Markdown	`public/images/`
A favicon	`public/`
A logo imported into a component	`src/assets/`
An optimized image in an Astro component	`src/assets/`

World Bible Asset Structure

public/
  images/
    maps/
      global-map-2175.png
      europe-2175.png
      austral-confluence.png
    locations/
      new-york-harbor.png
      washington-capital-core.png
    characters/
      veritas-miraculo.png
      aurelian-rassendyll.png
    factions/
      house-valoire-symbol.svg
      house-miraculo-symbol.svg
  downloads/
    character-sheet-template.pdf
    region-template.pdf
    faction-template.pdf

Lesson Site Asset Structure

public/
  images/
    screenshots/
      terminal-create-astro.png
      vercel-output-directory.png
    diagrams/
      request-response-cycle.svg
      content-collection-flow.svg
    examples/
      folder-structure.png
  downloads/
    markdown-cheat-sheet.pdf
    deployment-checklist.pdf

Common Broken Path Mistakes

Using a local computer path

Bad:
<img src="C:\Users\Ray\Desktop\map.png">

Good:
<img src="/images/maps/map.png" alt="Map">

Including public in the URL

Bad:
![Map](/public/images/map.png)

Good:
![Map](/images/map.png)

Wrong relative path

Risky:
![Map](../../images/map.png)

Usually simpler:
![Map](/images/map.png)

Using SVG Files

SVG files are useful for icons, diagrams, faction symbols, logos, and simple maps.

public/images/diagrams/site-flow.svg

![Site flow diagram](/images/diagrams/site-flow.svg)

Images in MDX

![Character portrait](/images/characters/example-character.png)

You can also use HTML in MDX:

<img src="/images/characters/example-character.png" alt="Example character portrait" />

Deployment Checklist for Assets

[ ] All images are inside public/ or src/assets/
[ ] No local computer paths are used
[ ] public/ paths do not include the word public
[ ] File names match exactly, including capitalization
[ ] Images have useful alt text
[ ] Downloads open from the built site
[ ] npm run build succeeds
[ ] npm run preview shows working assets

Simple Rule of Thumb

Use public/ when you want a simple URL.
Use src/assets/ when an Astro component imports the file.
Use root paths for public files.
Never use local computer paths.
Always test with npm run build and npm run preview.