Working with Files

This guide covers creating and managing files in your PhantomStudio project, including pages, components, layouts, and blog posts. The File Tree, where you manage files directly, is in Code mode (switch in the header).

Project Structure

Every PhantomStudio project follows the Astro folder structure:

Key Folders

Creating Pages

Creating a New Page

In Design mode, open the page switcher at the top of the Builder and choose New page.

In Code mode, use the File Tree:

1. Click the New Page button in the File Tree header toolbar
2. Or click the + button that appears next to the src/pages folder when you hover over it

Create Page Modal

The Create Page modal lets you configure your new page.

Start from Template

Browse page templates opens the Templates tab of the Component Library, with ready-made pages (for example Landing Page, About Us, Services, Pricing, Contact and FAQ) built from sections.

File Format

Choose between:

• .astro - Full control with components and logic
• .mdx - Markdown with component support (great for content-heavy pages)

Layout

Pick one of your project's layouts (from src/layouts/), or Blank (no layout).

Rendering

Choose Static (built when you publish), Dynamic (built on every visit) or Dynamic, cached (built on demand, reused for a while). See Rendering.

Contact Form Backend

Contact pages and contact sections send their submissions wherever Forms settings (Site ▾ › Forms settings, or ⌘K › Forms settings) points. The choice is saved in src/config/forms.json and applies to every form on the site:

• Formspree - Enter your form ID
• Web3Forms - Enter your access key
• Custom endpoint - Enter the full URL your provider gives you for the form, such as https://submit-form.com/your-form-id for Formspark. Works with any service that accepts a form POST
• WordPress - Delivered by wp_mail through the PhantomWP Connect plugin (needs a connected WordPress site)

src/lib/forms.ts reads that file (as @/config/forms.json, since @/ points at src/) and is rewritten when you save Forms settings, so don't put custom code in it. See Forms for details.

Creating Pages in Subfolders

To create nested URLs like /services/web-design:

1. Right-click the parent folder (e.g., src/pages/services)
2. Select New Page
3. The page will be created in that folder

Page File Names and URLs

File names become URLs:

Creating Components

Components are reusable pieces of UI. Create them in src/components/.

Creating a New Component

In Design mode, choose New component in the Builder's page switcher.

In Code mode:

1. Click the New Component button in the File Tree header toolbar
2. Or click the + button that appears next to src/components when you hover over it

Via Context Menu

1. Right-click src/components (or any subfolder)
2. Select New Component

Create Component Modal

The Create Component modal lets you configure your new component:

Component Name

Enter a name for your component. It will be converted to PascalCase automatically (e.g., "my card" becomes "MyCard").

Component Templates

Choose a starting template:

For "Component with Props", you can define custom props with names, types (string, number, boolean), and default values.

Component File Structure

A basic component looks like this:

---
// Props interface
interface Props {
  title: string;
  description?: string;
}

const { title, description } = Astro.props;
---

<div class="card">
  <h3>{title}</h3>
  {description && <p>{description}</p>}
</div>

Using Components

Import and use components in your pages:

---
import Card from '../components/Card.astro';
---

<Card title="My Card" description="Card content here" />

Extracting Components

Turn any part of a page into a reusable component.

From the Builder

1. Right-click an element in the Builder (or select it and press ⌘K)
2. Choose Make a component…
3. Check the suggested name and the props it gets, then confirm
4. The code is moved to a new file and replaced with a component tag

If the element has look-alikes next to it (other cards in the same grid, for example), Make a component… turns them all into one component, and the parts that differ become props.

What Happens

When you extract a component:

1. The selected HTML/JSX is copied to a new file
2. The file is created in src/components/
3. The original code is replaced with <ComponentName />
4. The import is added to the page automatically

Before:

<section class="hero">
  <h1>Welcome</h1>
  <p>Hero description</p>
</section>

After:

---
import Hero from '../components/Hero.astro';
---

<Hero />

Creating Blog Posts

Blog posts are created in src/pages/blog/ as MDX files.

Creating a New Blog Post

1. Click the + button next to src/pages/blog
2. Or right-click src/pages/blog and select New Blog Post

Blog Post Structure

Blog posts use MDX (Markdown with components):

---
title: "My Blog Post"
description: "A short description"
pubDate: 2024-01-15
author: "Your Name"
tags: ["tutorial", "astro"]
---

# Introduction

Write your content in Markdown...

## Using Components

You can import and use components:

import Card from '../../components/Card.astro';

<Card title="Example" />

Blog Post Frontmatter

Common frontmatter fields:

Creating Layouts

Layouts wrap your pages with common elements like headers and footers.

Via Context Menu

1. Right-click src/layouts
2. Select New Layout
3. Enter a name (e.g., "BlogLayout")

Layout Structure

---
interface Props {
  title: string;
  description?: string;
}

const { title, description } = Astro.props;
---

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width" />
  <title>{title}</title>
  <meta name="description" content={description} />
</head>
<body>
  <header>
    <!-- Navigation -->
  </header>
  
  <slot />
  
  <footer>
    <!-- Footer content -->
  </footer>
</body>
</html>

Using Layouts

Wrap your pages with a layout:

---
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout title="My Page">
  <main>
    <!-- Page content goes in the slot -->
  </main>
</BaseLayout>

Managing Files

Renaming Files

1. Right-click the file
2. Select Rename
3. Enter the new name
4. Press Enter

Or click the pencil icon that appears on hover.

Duplicating Files

1. Right-click the file
2. Select Duplicate
3. Enter a new name
4. Click Duplicate

Moving Files

Drag and drop files between folders:

1. Click and hold a file
2. Drag to the target folder
3. Release to move

Deleting Files

1. Right-click the file or folder
2. Select Delete
3. Confirm the deletion

Creating Folders

1. Right-click the parent folder
2. Select New Folder
3. Enter a name
4. Press Enter

File Search

Use the search bar at the top of the File Tree:

1. Click the search icon or press /
2. Type part of the filename
3. Results filter in real-time

Quick Reference

Next Steps

• Design mode - Edit pages and components visually in the Builder
• Component Library - Browse pre-built components
• Media Manager - Add images to your pages