Website Setup Guide

This guide explains how to convert the Game Design Document markdown files into a professional website using VitePress.

🚀 VitePress Setup

VitePress is fast, modern, and perfect for documentation websites. It's already configured for your Game Design Document.

Installation

# Install VitePress
npm install -D vitepress

# Or if you prefer yarn
yarn add -D vitepress

Usage

# Development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Or use the deploy script for convenience
./deploy.sh dev      # Start development server
./deploy.sh build    # Build for production
./deploy.sh preview  # Preview production build
./deploy.sh deploy   # Build and prepare for deployment

Configuration

The .vitepress/config.mts file is already configured with:

• Professional theme with navigation
• Search functionality
• Social links and footer
• Responsive design
• Dark/light mode switching

📁 File Structure

docs/game-design/
├── .vitepress/
│   └── config.mts          # VitePress configuration
├── index.md                # Homepage with hero section
├── game-overview.md        # Game concept and overview
├── game-mechanics.md       # Gameplay mechanics and systems
├── art-style.md           # Art direction and style guide
├── audio-design.md        # Audio design and implementation
├── technical-specs.md     # Technical requirements and specs
├── development-timeline.md # Project timeline and milestones
├── asset-pipeline.md      # Asset creation and integration
├── testing-strategy.md    # Testing approach and procedures
├── website-setup.md       # This file
└── package.json           # Node.js dependencies and scripts

🎨 Customization

Styling

VitePress includes:

• Dark/Light Mode: Automatic theme switching
• Responsive Design: Mobile-friendly layout
• Custom Colors: Brand-appropriate color schemes
• Typography: Readable fonts and text sizing

Navigation

• Main Navigation: Top-level document sections
• Sidebar Navigation: Detailed document structure
• Breadcrumbs: Current location indication
• Search: Full-text search across all content

Features

• Code Highlighting: Syntax highlighting for code blocks
• Copy Buttons: Easy code copying
• Edit Links: Direct editing on GitHub
• Last Updated: Automatic update timestamps
• Social Links: GitHub, Twitter, Discord integration

🌐 Deployment Options

GitHub Pages (Automated)

Deploy automatically using GitHub Actions:

1. Enable GitHub Pages in your repository settings
2. Push to main branch - GitHub Actions will automatically deploy
3. Your site will be available at: https://your-username.github.io/spooky-game-jam-2025/

The GitHub Actions workflow (.github/workflows/deploy-docs.yml) is already configured to:

• Build the VitePress site automatically
• Deploy to GitHub Pages on every push to main
• Only trigger when documentation files change
• Use the latest Node.js and VitePress versions

Manual GitHub Pages Deployment

If you prefer manual deployment:

# Build the site
npm run build

# Deploy to GitHub Pages
# Push the dist/ folder to gh-pages branch

Netlify

Deploy to Netlify with automatic builds:

1. Connect your GitHub repository
2. Set build command: npm run build
3. Set publish directory: dist
4. Deploy automatically on every push

Vercel

Deploy to Vercel with zero configuration:

1. Connect your GitHub repository
2. Vercel will auto-detect VitePress
3. Deploy automatically on every push

Custom Hosting

Build and deploy to any static hosting service:

# Build the site
npm run build

# Upload the dist/ directory to your hosting service

🔧 Advanced Configuration

Custom Domain

Add a custom domain to your site:

1. GitHub Pages: Add CNAME file to repository
2. Netlify: Configure custom domain in settings
3. Vercel: Add domain in project settings

Analytics

Add analytics to track site usage by updating the VitePress config:

// .vitepress/config.mts
export default defineConfig({
  // Add analytics configuration
  analytics: {
    id: 'G-XXXXXXXXXX'
  }
})

Search

Search is already configured with local search functionality.

Comments

Add commenting system by updating the VitePress config:

// .vitepress/config.mts
export default defineConfig({
  themeConfig: {
    // Add comments configuration
    comments: {
      provider: 'giscus',
      repo: 'your-username/your-repo',
      repoId: 'your-repo-id',
      categoryId: 'your-category-id'
    }
  }
})

📱 Mobile Optimization

VitePress includes mobile optimization:

• Responsive Design: Adapts to all screen sizes
• Touch Navigation: Touch-friendly navigation
• Fast Loading: Optimized for mobile networks
• Offline Support: Basic offline functionality

🔍 SEO Optimization

Built-in SEO features:

• Meta Tags: Proper meta descriptions and titles
• Structured Data: Schema.org markup
• Sitemap: Automatic sitemap generation
• Robots.txt: Search engine directives
• Open Graph: Social media sharing optimization

🛠️ Maintenance

Regular Updates

• Content Updates: Update documentation regularly
• Dependency Updates: Keep VitePress updated
• Security Updates: Apply security patches
• Performance Monitoring: Monitor site performance

Backup Strategy

• Version Control: All content in Git
• Automated Backups: GitHub provides backup
• Local Backups: Regular local backups
• Export Options: Export to various formats

📊 Analytics and Monitoring

Built-in Analytics

• Page Views: Track page popularity
• User Behavior: Understand user navigation
• Search Queries: See what users search for
• Performance: Monitor site performance

External Analytics

• Google Analytics: Detailed user analytics
• Plausible: Privacy-focused analytics
• Fathom: Simple, privacy-focused analytics
• Mixpanel: Advanced user analytics

🎯 Best Practices

Content Organization

• Clear Structure: Logical document hierarchy
• Consistent Formatting: Uniform markdown formatting
• Regular Updates: Keep content current
• Version Control: Track all changes

Performance

• Optimize Images: Compress and optimize images
• Minimize Assets: Reduce file sizes
• CDN Usage: Use content delivery networks
• Caching: Implement proper caching strategies

Accessibility

• Alt Text: Provide image alt text
• Heading Structure: Use proper heading hierarchy
• Color Contrast: Ensure good color contrast
• Keyboard Navigation: Support keyboard navigation

🆘 Troubleshooting

Common Issues

• Build Failures: Check VitePress configuration
• Missing Content: Verify file paths and names
• Styling Issues: Check theme configuration
• Search Problems: Verify search setup

Getting Help

• Documentation: Check VitePress documentation
• Community: Join VitePress communities
• Issues: Report issues on GitHub
• Support: Contact support channels

---

This website setup guide should help you get your Game Design Document online quickly and professionally with VitePress.