Docs/Media Manager

Media Manager

Upload, organize, and manage images and files in your project.

Media Manager

PhantomStudio gives you three ways to work with images: the Media Library for a visual gallery, the Builder for picking images while you edit a page, and the File Tree (Code mode) for file-based management. All of them work with images in src/media/, which Astro optimizes automatically.

Media Library

Open Site ▾ › Media Manager (in the Content column), or press ⌘K (Ctrl+K) and type "Media Manager". The Media Library opens with a visual grid of all your images.

Features

The Media Library shows:

  • Image thumbnails - Visual previews of all images in src/media/
  • Search bar - Filter images by filename
  • Upload - Upload images from your computer, or drop them on the grid

Uploading Images

Drag and drop:

  1. Open the Media Library
  2. Drag image files from your computer
  3. Drop them on the grid

Upload button:

  1. Click Upload
  2. Select one or more images from your computer
  3. Files upload to src/media/

Only image files are accepted.

Using Images

Hover over any image to see action buttons:

ActionDescription
Insert at CursorAdds import + Image component where the cursor is in the code editor
Copy ImportCopies just the import statement to clipboard
Copy Full CodeCopies complete code with frontmatter
DeleteRemoves the image from your project

Insert at Cursor

This is the quickest way to add an image to a file in the code editor (Code mode):

  1. Put your cursor in the file where you want the image
  2. Open the Media Library
  3. Hover over an image
  4. Click Insert at Cursor

The following code is inserted:

---
import { Image } from 'astro:assets';
import heroImage from '../media/hero.jpg';
---

<Image src={heroImage} alt="hero" />

Astro Optimization

Images stored in src/media/ get automatic optimization:

  • Format conversion - WebP/AVIF for supported browsers
  • Responsive sizes - Multiple sizes generated
  • Lazy loading - Images load as they come into view

In the Builder

While you edit a page in Design mode, the Media Library opens wherever you need an image:

  • Add › Image opens the Media Library (upload or pick) and inserts an optimized <Image> with its imports.
  • Choose from media on an image's card in the Builder points the image at another file.
  • Replace image in the preview's selection toolbar, or Replace image… in the Builder's right-click menu, does the same from the page.

In this mode the library says Click an image to use it, or upload a new one.

File Tree

In Code mode, the File Tree also provides media management with more file-level control.

Project Structure

src/ media/ # Optimized images (recommended) components/ layouts/ pages/ public/ # Static files (favicon, etc.)

Two Media Locations

src/media/ - Images with Astro optimization (recommended)

  • Automatic format conversion
  • Responsive sizes
  • Lazy loading

public/ - Static files served as-is

  • Favicon and app icons
  • robots.txt
  • Open Graph default images
  • Files that must keep exact format

Uploading via File Tree

To src/media/:

  1. Right-click the src/media folder
  2. Select Upload Images
  3. Drag and drop or browse

To public/:

  1. Right-click the public folder
  2. Select Upload Files
  3. Drag and drop or browse

Drag and Drop to Editor

Drag images directly from the File Tree into your code:

  1. Find the image in src/media/
  2. Drag it from the File Tree
  3. Drop it into your code editor
  4. The import and Image component code is inserted

Right-Click Menu

Right-click any image in src/media/ for quick actions:

ActionDescription
Insert at CursorAdds code at your cursor
Copy ImportCopies import statement
Copy Code SnippetCopies complete code
Copy PathCopies file path
DeleteRemoves the file

File Management

The File Tree also supports:

  • Create folders - Right-click > New Folder
  • Rename files - Right-click > Rename
  • Duplicate files - Right-click > Duplicate
  • Move files - Drag between folders
  • Search - Use the search bar to filter

Code Examples

Using the Image Component

---
import { Image } from 'astro:assets';
import heroImage from '../media/hero.jpg';
---

<Image src={heroImage} alt="Hero image" width={800} />

With Custom Dimensions

<Image 
  src={heroImage} 
  alt="Hero" 
  width={1200} 
  height={600}
  class="rounded-lg shadow-lg"
/>

In Markdown/MDX

import heroImage from '../media/hero.jpg';

<Image src={heroImage} alt="Hero" />

Best Practices

File Naming

Use descriptive, URL-friendly names:

  • Good: team-photo-2024.jpg, product-dashboard.png
  • Avoid: IMG_2847.jpg, Screenshot 2024-01-15.png

Folder Organization

Organize images by purpose:

src/media/ blog/ # Blog post images products/ # Product photos team/ # Team photos icons/ # Icon files

Image Sizing

  • Hero images: 1920px wide maximum
  • Content images: 800-1200px wide
  • Thumbnails: 400px wide
  • Icons: SVG preferred

Alt Text

Always add descriptive alt text:

  • Describe what's in the image
  • Keep it concise (125 characters or less)
  • Don't start with "Image of"

Troubleshooting

Upload Failed

If uploads fail:

  1. Check file size (large files may timeout)
  2. Verify file type is supported
  3. Ensure your workspace (Codespace or local Docker container) is running
  4. Try refreshing the page

Image Not Showing

If an image doesn't appear:

  1. Verify the import path is correct
  2. Check the file exists in src/media/
  3. Make sure you're using the Image component
  4. Refresh the preview

Thumbnails Not Loading

If Media Library thumbnails don't load:

  1. Wait a moment - previews load asynchronously
  2. Check the status dot in the header for a connection problem
  3. Refresh the Media Library

Next Steps

Previous
Section Library
Next
Font Manager