Quick Start

Ready to create your first Astro site? This guide will walk you through the complete process from signup to deployment. The entire workflow happens in your browser - no local setup required.

Overview

Here's what we'll do:

1. Sign up and connect GitHub (2 minutes)
2. Create your first project (1 minute)
3. Explore the IDE (5 minutes)
4. Deploy to Vercel (2 minutes)

Total time: ~10 minutes

Step 1: Sign Up and Connect GitHub

Create Your Account

1. Visit wp2astro.com
2. Click "Get Started" or "Sign Up"
3. Enter your email and create a password
4. Verify your email address

[screenshot of the dashboard]

Connect GitHub

After signing up, you'll be prompted to connect GitHub:

1. Click "Connect GitHub Account"
2. Authorize WP2Astro in the GitHub popup
3. Choose repository visibility (public or private recommended)

Why GitHub?

• Stores your code with version control
• Enables GitHub Codespaces (cloud IDE)
• Allows automatic deployments
• Free for unlimited public/private repos

Step 2: Create Your First Project

Now let's create an Astro site!

From the Dashboard

1. Click "Create New Project"
2. You'll see the project creation form

[screenshot of create project form]

Choose Your Starting Point

You have three options:

Option A: Start from Scratch (Recommended for Beginners)

Perfect if you want to learn Astro or build a new site:

1. Project Name: Enter a name (e.g., "my-blog")
2. Template: Choose "Starter" or "Blog"
3. Theme: Select a theme (you can change this later)
4. Repository: Choose public or private
5. Click "Create Project"

No WordPress site? No problem! This creates a fresh Astro site with example content.

Option B: Import from WordPress

Have an existing WordPress site you want to migrate?

1. Project Name: Enter a name
2. Upload WordPress XML:
   • Go to your WordPress admin → Tools → Export
   • Download the XML file
   • Upload it here
3. Choose your template and theme
4. Click "Create Project"

WP2Astro will convert your posts, pages, and media to Astro.

Option C: Choose a Template Type

Select from specialized templates:

• Blog: Personal blog with posts and categories
• Portfolio: Showcase your work
• Documentation: For technical docs
• Marketing: Landing pages and marketing site
• Business: Professional business site

What Happens Next

After clicking "Create Project", WP2Astro:

This takes about 2-3 minutes. You'll see a loading screen with helpful tips.

Step 3: Access Your Project IDE

Once your project is created, you'll be redirected to your dashboard.

Understanding Codespace Status

Your project shows a codespace status:

• Off: Codespace is not running (save resources)
• Starting: Codespace is booting up (takes 30-60 seconds)
• Running: Ready to use!

[screenshot of codespace status]

Create or Start Your Codespace

If this is a new project:

1. Click "Create Codespace" on your project
2. Wait 30-60 seconds for it to provision
3. Once "Running", you can access the IDE

If you already have a codespace:

1. Click "Start Codespace" if it's off
2. Wait for status to change to "Running"
3. Access the IDE

Two Ways to Edit

WP2Astro offers two editing modes:

Content Editor (Simple Mode)

Perfect for writing blog posts and editing pages:

1. Click "Content" on your project
2. Edit markdown/MDX files
3. Use the WYSIWYG editor
4. Changes auto-save

[screenshot of content editor]

Best for: Writers, bloggers, content creators

Dev Mode (Advanced Mode)

Full IDE with code editor and terminal:

1. Click "Dev Mode" on your project
2. Access Monaco code editor
3. Full file tree navigation
4. Terminal access
5. Git integration
6. Live preview

[screenshot of dev mode]

Best for: Developers, designers, advanced users

Step 4: Explore the IDE

Let's look at what you can do in Dev Mode:

File Tree

On the left, you'll see your project structure:

[screenshot of file tree]

Code Editor

The Monaco editor (same engine as VS Code):

• Syntax highlighting for Astro, TypeScript, CSS
• Auto-completion
• Multi-file tabs
• Auto-save (saves every 500ms)
• Find and replace

Live Preview

On the right side, see your changes in real-time:

• Updates instantly as you type
• Responsive preview (desktop/mobile)
• Refresh button to reload
• Console for debugging

[screenshot of IDE interface]

Making Your First Edit

Let's edit the homepage:

1. Click src/pages/index.astro in the file tree
2. Find the page title
3. Change it to something like "Welcome to My Site"
4. Watch the preview update automatically!

---
// Your frontmatter here
---

<Layout title="Welcome to My Site">
  <h1>Welcome to My Site</h1>
  <p>This is my new Astro site built with WP2Astro!</p>
</Layout>

Terminal Access (Advanced)

Click the terminal icon to access the command line:

# Check Astro version
npm run astro -- --version

# Add a package
npm install date-fns

# Run build
npm run build

Step 5: Deploy to Vercel

Ready to make your site live? Deploy to Vercel with one click!

Connect Vercel

1. Go back to your dashboard
2. In the sidebar, click "Connect Vercel"
3. Enter your Vercel token or connect your account
4. Authorize the integration

[screenshot of Vercel connection modal]

Deploy Your Project

1. On your project card, click "Setup Deployment"
2. Select your project from the modal
3. Click "Deploy"
4. Wait 2-3 minutes for deployment

[screenshot of deployment status]

Deployment Status

Your project will show:

• Building: Vercel is building your site
• Live: Your site is deployed! 🎉
• Failed: Check the logs (rare)

Click "View Site" to see your live site!

Automatic Deployments

After the initial setup, every time you make changes:

1. Edit files in the IDE
2. Changes auto-save and commit to GitHub
3. Vercel automatically detects changes
4. New deployment starts automatically
5. Your site updates in ~2 minutes

No manual deployment needed!

What You Just Built

Congratulations! You now have:

• ✅ A GitHub repository with your Astro site code
• ✅ A cloud development environment (Codespace)
• ✅ A browser-based IDE for editing
• ✅ A live website deployed to Vercel
• ✅ Automatic deployments on every change

All without installing anything locally!

Next Steps

Learn the IDE

• Explore the IDE Overview
• Learn about Content Editor
• Master Dev Mode

Customize Your Site

• Edit your homepage (src/pages/index.astro)
• Add new pages (src/pages/about.astro)
• Create blog posts (src/content/blog/)
• Change colors and fonts (src/styles/)

Add Content

If you started from scratch, try adding your first blog post:

1. In Dev Mode, navigate to src/content/blog/
2. Create a new file: my-first-post.mdx
3. Add frontmatter and content:

---
title: "My First Post"
description: "Welcome to my blog!"
publishDate: 2024-02-20
author: "Your Name"
---

# Welcome!

This is my first blog post using Astro and WP2Astro.

## Why Astro?

Astro is amazing because...

Import WordPress Content (Optional)

If you started from scratch but want to import WordPress content later:

1. Go to your WordPress site
2. Tools → Export → Download XML
3. In WP2Astro, use the WordPress Import feature
4. Upload your XML file
5. Content will be merged into your existing site

Tips for Success

Managing Codespaces

• Stop when not using: Codespaces auto-stop after 4 hours of inactivity
• Delete unused ones: Free up resources by deleting old codespaces
• Monitor your quota: GitHub shows remaining hours in your account

Saving Changes

• Auto-save: Changes save automatically every 500ms
• Git commits: Use Git integration to commit important milestones
• Backup: Your code is always backed up in GitHub

Performance

• Build time: First build takes ~1 minute, subsequent builds are faster
• Preview updates: Changes appear instantly in preview
• Deployment: Vercel deployments take 2-3 minutes

Getting Help

• Documentation: Browse the rest of the docs
• Discord: Join our community for help
• Support: Email support@wp2astro.com
• GitHub Issues: Report bugs on our GitHub

Common Questions

Q: Do I need to keep my codespace running?
A: No! Codespaces auto-stop after 4 hours. Start them again when you need to edit.

Q: What if I exceed GitHub's free tier?
A: You can upgrade to GitHub Pro for more hours, or work locally by cloning your repo.

Q: Can I edit files locally instead?
A: Yes! Clone your GitHub repository and work locally if you prefer. Changes sync back.

Q: How do I update my site after the initial deployment?
A: Just edit files in the IDE. Vercel automatically redeploys on every commit.

Q: Can I use my own domain?
A: Yes! Configure custom domains in your Vercel project settings.

Q: What if I don't have a WordPress site?
A: No problem! Start from scratch with one of our templates. WordPress import is optional.

Troubleshooting

Codespace Won't Start

• Check your GitHub account status
• Verify you haven't exceeded your monthly quota
• Try deleting and recreating the codespace
• Make sure your repository isn't deleted

Deployment Failed

• Check Vercel is connected properly
• Verify your Vercel token is valid
• Check build logs in Vercel dashboard
• Ensure your code doesn't have errors

Preview Not Updating

• Try refreshing the preview panel
• Check the terminal for build errors
• Restart the dev server from terminal

Ready to dive deeper? Continue to Core Concepts to understand how everything works under the hood!