# Setup Guide

Complete step-by-step guide to setting up and customizing your Astro portfolio template.

## Table of Contents

1. [Initial Setup](#initial-setup)
2. [Template Personalization](#template-personalization)
3. [Content Customization](#content-customization)
4. [Media Assets](#media-assets)
5. [Design Customization](#design-customization)
6. [Deployment](#deployment)
7. [Optional Features](#optional-features)
8. [Troubleshooting](#troubleshooting)

## Initial Setup

### Prerequisites

Before you begin, make sure you have:

- **Node.js 18 or later** - [Download here](https://nodejs.org/)
- **pnpm** (recommended) - Install with `npm install -g pnpm`
- **Git** - [Download here](https://git-scm.com/)
- A **code editor** (VS Code recommended)

### Installation

1. **Clone or download the template**
   ```bash
   git clone <repository-url>
   cd astro-template
   ```

2. **Install dependencies**
   ```bash
   pnpm install
   ```

3. **Verify installation**
   ```bash
   pnpm dev
   ```
   Open [http://localhost:4321](http://localhost:4321) - you should see the template with placeholder content.

## Template Personalization

### Option 1: Interactive Setup (Recommended)

Run the setup wizard to personalize all template files:

```bash
node init-template.js
```

The wizard will ask for:
- Your name and profession
- Site URL and description
- Contact information (email, location)
- Social media links
- Company/branding details
- Cloudflare project name

Review the summary and confirm to apply changes.

### Option 2: Manual Configuration

Edit `template.config.json` with your information, then run:

```bash
node init-template.js --config
```

### What Gets Updated

The setup script updates:
- `src/consts.ts` - Site-wide constants
- `src/components/BaseHead.astro` - SEO and structured data
- `src/components/Navigation.astro` - Branding
- `src/components/Footer.astro` - Contact and social links
- `src/content/sections/hero.mdx` - Hero section
- `src/content/sections/experience.mdx` - Work history
- `src/content/pages/contact.mdx` - Contact page
- `astro.config.mjs` - Site URL
- `wrangler.jsonc` - Cloudflare project name
- `package.json` - Package name

## Content Customization

### Homepage Sections

Edit files in `src/content/sections/`:

#### Hero Section (`hero.mdx`)

```yaml
---
headlineLine1: "YOUR NAME"
headlineLine2: "HERE"
portfolioYear: "Portfolio 2025"
location: "Your City, State"
locationLabel: "Location"
bio: "Your professional bio..."
---
```

#### Experience (`experience.mdx`)

```yaml
---
sectionTitle: "Experience"
sectionSubtitle: "History"
sectionLabel: "/// Your professional journey."
entries:
  - systemId: "SYS.01"
    status: "ACTIVE"
    dates: "2020 — PRESENT"
    company: "Company Name"
    role: "Your Role"
    tags: ["Skill 1", "Skill 2"]
    description: "What you do..."
    achievements:
      - label: "Projects"
        text: "Notable projects..."
    link:
      url: "https://company.com"
      text: "Visit Website"
---
```

#### Skills (`skills.mdx`)

```yaml
---
sectionTitle: "Technical"
sectionSubtitle: "Arsenal"
description: "Your skills and specialties"
skills:
  - id: "01"
    domain: "Primary Skill"
    tools: "Tool 1 • Tool 2 • Tool 3"
    proficiency: "Expert"
---
```

#### Featured Project (`featured-project.mdx`)

```yaml
---
role: "Your Role"
client: "Client Name"
year: "2024"
region: "Global"
projectTitle: "Project"
projectSubtitle: "Name"
projectDescription: "Brief description..."
stats:
  - label: "Category"
    value: "Value"
videoUrl: "/media/your-video.mp4"
linkUrl: "/blog/your-case-study/"
---
```

### Blog Posts

#### Creating a New Post

1. Create a new MDX file in `src/content/blog/`:
   ```bash
   touch src/content/blog/my-new-post.mdx
   ```

2. Add frontmatter and content:
   ```mdx
   ---
   title: 'Your Post Title'
   description: 'Brief description for SEO'
   pubDate: 'Dec 27 2024'
   heroImage: '../../assets/hero-image.avif'
   featured: false
   category: 'Tutorial'
   tags: ['Web Dev', 'Astro']
   ---

   ## Introduction

   Your content here...
   ```

3. The file name becomes the URL slug:
   - `my-new-post.mdx` → `/blog/my-new-post/`

#### Blog Frontmatter Fields

**Required:**
- `title` - Post title
- `description` - SEO description
- `pubDate` - Publication date

**Optional:**
- `heroImage` - Header image path
- `featured` - Set to `true` to feature on blog index
- `category` - For filtering
- `tags` - Array of tags
- `updatedDate` - Last update date

#### Example Blog Post Template

See `dev/blog_template.mdx` for a complete example.

### Contact Page

Edit `src/content/pages/contact.mdx`:

```yaml
---
pageTitleLine1: "Get In"
pageTitleLine2: "Touch"
availabilityText: "Available for new projects"
email: "your@email.com"
location: "Your City"
coordinates: "XX.XXXX° N, XX.XXXX° W"
socialLinks:
  - name: "LinkedIn"
    url: "https://linkedin.com/in/yourprofile"
formLabels:
  name: "/// Your Name"
  email: "/// Your Email"
  subject: "/// Subject"
  message: "/// Message"
  submit: "Send Message"
subjectOptions:
  - value: "project"
    label: "Project Inquiry"
---
```

## Media Assets

### Images

#### Placeholder Images to Replace

See `public/media/PLACEHOLDER_ASSETS.md` for a complete list.

**Priority replacements:**
1. Default OG image: `src/assets/nicholai-medium-portrait.avif`
2. Blog post hero images
3. Featured project video
4. Favicons

#### Adding Your Images

1. **For blog/content images** (optimized by Astro):
   - Place in `src/assets/`
   - Reference: `../../assets/image-name.jpg`

2. **For videos/large files** (static):
   - Place in `public/media/`
   - Reference: `/media/filename.mp4`

#### Converting to AVIF

AVIF provides superior compression. Convert your images:

```bash
# Convert all images
pnpm convert:avif:all

# Convert specific formats
pnpm convert:avif:jpeg
pnpm convert:avif:png

# Custom quality (0-100)
node src/utils/convert-to-avif.js --jpeg --quality 80
```

### Favicons

Generate a complete favicon set:

1. Use [favicon.io](https://favicon.io) or [RealFaviconGenerator](https://realfavicongenerator.net)
2. Replace files in `public/`:
   - `favicon.ico`
   - `favicon-32.png`
   - `favicon-192.png`
   - `apple-touch-icon.png`
   - `favicon.svg`

## Design Customization

### Color Scheme

Edit CSS custom properties in `src/styles/global.css`:

```css
:root {
  /* Background colors */
  --theme-bg-primary: #0B0D11;
  --theme-bg-secondary: #12141A;

  /* Text colors */
  --theme-text-primary: #E8E9ED;
  --theme-text-muted: #9CA3B3;

  /* Accent colors */
  --brand-accent: #3D8374;
}
```

### Typography

Fonts are loaded in `src/components/BaseHead.astro`. To change:

1. Update Google Fonts link (line 124-137)
2. Update font families in `global.css`

### Design System

Full design documentation in `dev/design.json`:
- Color palettes
- Typography scales
- Spacing system
- Grid system
- Component patterns

## Deployment

### Cloudflare Pages (Default)

#### Option 1: CLI Deployment

```bash
pnpm deploy
```

#### Option 2: Git Integration

1. Push your code to GitHub/GitLab
2. Go to [Cloudflare Pages Dashboard](https://dash.cloudflare.com/pages)
3. Connect your repository
4. Configure build settings:
   - **Build command**: `pnpm build`
   - **Build output directory**: `dist`
   - **Root directory**: `/`
   - **Node version**: 18 or later
5. Deploy!

### Environment Variables

For Cloudflare Pages deployment:

1. Go to your project settings → Environment Variables
2. Add any required variables (e.g., API keys for forms)

### Custom Domain

1. In Cloudflare Pages, go to Custom Domains
2. Add your domain
3. Follow DNS configuration instructions

### Other Platforms

**Vercel:**
```bash
# Change adapter
pnpm remove @astrojs/cloudflare
pnpm add @astrojs/vercel
```

Update `astro.config.mjs`:
```js
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  adapter: vercel(),
  // ...
});
```

**Netlify:**
```bash
pnpm remove @astrojs/cloudflare
pnpm add @astrojs/netlify
```

**Static (no adapter):**
Remove the `adapter` from `astro.config.mjs` for pure static site generation.

## Optional Features

### AI-Powered Git Commits

1. Get an API key from [OpenRouter.ai](https://openrouter.ai)

2. Create `src/utils/.env`:
   ```
   OPENROUTER_API_KEY=your_key_here
   ```

3. Stage changes and run:
   ```bash
   pnpm commit
   ```

The script generates a commit message, lets you edit it, and optionally pushes.

### Analytics

Add analytics to `src/components/BaseHead.astro`:

```astro
<!-- Example: Plausible -->
<script defer data-domain="yoursite.com" src="https://plausible.io/js/script.js"></script>
```

### Contact Form Integration

The template includes a contact form. To make it functional:

**Option 1: Cloudflare Forms** (Recommended)
- Forms are built-in with Cloudflare Pages
- View submissions in your Cloudflare Dashboard

**Option 2: External Service**
- [Formspree](https://formspree.io)
- [Web3Forms](https://web3forms.com)
- [Netlify Forms](https://www.netlify.com/products/forms/)

Update the form action in `src/pages/contact.astro`.

## Troubleshooting

### Build Errors

**"Cannot find module..."**
```bash
# Reinstall dependencies
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

**TypeScript errors**
```bash
# Generate types
pnpm cf-typegen
```

### Dev Server Issues

**Port already in use**
```bash
# Use a different port
pnpm dev -- --port 3000
```

**Changes not reflecting**
- Hard reload: Ctrl+Shift+R (Windows) / Cmd+Shift+R (Mac)
- Clear `.astro` cache and restart

### Image Issues

**Images not loading**
- Check file paths (relative vs absolute)
- Ensure images are in correct directory
- Restart dev server

**AVIF conversion fails**
```bash
# Install Sharp dependencies
pnpm install sharp
```

### Deployment Issues

**Build fails on Cloudflare**
- Check Node version (should be 18+)
- Verify `pnpm build` works locally
- Check build logs for specific errors

**404 on deployed site**
- Verify build output directory is `dist`
- Check routing/links are correct
- Clear Cloudflare cache

## Next Steps

1. **Test your site locally**: `pnpm dev`
2. **Build for production**: `pnpm build`
3. **Preview build**: `pnpm preview`
4. **Deploy**: `pnpm deploy`
5. **Update `dev/continuity.md`** with your changes

## Support

- **Astro Documentation**: [docs.astro.build](https://docs.astro.build)
- **Cloudflare Pages**: [developers.cloudflare.com/pages](https://developers.cloudflare.com/pages)
- **Tailwind CSS**: [tailwindcss.com/docs](https://tailwindcss.com/docs)

---

**Need help?** Check the existing blog posts for examples of how to use various features.