Working with Files

This guide covers creating and managing files in your PhantomWP project, including pages, components, layouts, and blog posts.

Project Structure

Every PhantomWP project follows the Astro folder structure:

Key Folders

Creating Pages

Creating a New Page

There are two ways to create a page with the + button:

1. Click the + Page button in the File Tree header toolbar
2. 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:

Page Templates

Choose a starting template:

File Format

Choose between:

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

Layout Selection

Select which layout to use:

• BaseLayout - Minimal wrapper
• PageLayout - Standard page layout
• ContentLayout - Optimized for text content (prose styling)

Contact Form Backend

For Contact pages, configure the form service:

• Formspree - Enter your Form ID
• Web3Forms - Enter your Access Key
• Configure later - Add the backend manually

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

There are two ways to create a component:

1. Click the + Component button in the File Tree header toolbar
2. 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 section of a page into a reusable component.

From the HTML Tree View

1. Open the Tree tab in the right panel
2. Right-click an element
3. Select Extract Component
4. Enter a component name
5. The code is moved to a new file and replaced with a component tag

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

• Visual Editor - Edit components visually
• Component Library - Browse pre-built components
• Media Manager - Add images to your pages