tigerstyle-whiskers/docs/DEVELOPER.md

# TigerStyle Whiskers Documentation - Developer Guide

This guide is for developers who need to build, deploy, or contribute to the documentation site.

## 🐳 Docker Deployment

### Prerequisites
- Docker and Docker Compose
- Caddy Docker Proxy network setup
- Domain configured for `whiskers.$DOMAIN`

### Quick Deployment
```bash
# Build and start the container
docker compose up -d

# Check container status
docker compose ps

# View logs
docker compose logs tigerstyle-whiskers-docs

# Stop and remove
docker compose down
```

### Domain Access
The container is configured to be accessible via Caddy Docker Proxy at:
```
https://whiskers.example.com
```

Replace `example.com` with your actual domain set in the `DOMAIN` environment variable.

## 🛠️ Development Setup

### Local Development
```bash
npm install
npm run dev          # Start development server
npm run build        # Build for production
npm run preview      # Preview production build
```

Visit `http://localhost:4323/whiskers` to view the documentation.

### Available Scripts
```bash
npm run astro        # Run Astro CLI commands
npm run astro check  # Validate configuration
```

## 🐳 Docker Architecture

### Multi-stage Build
1. **Builder Stage**: Node.js 18 Alpine for building the Astro site
2. **Production Stage**: Caddy 2 Alpine for serving static files

### Caddy Configuration
- **Compression**: Gzip encoding for all responses
- **Security Headers**: XSS protection, MIME sniffing prevention
- **Caching**: Aggressive caching for static assets (1 year)
- **Health Check**: `/health` endpoint for monitoring
- **SPA Routing**: Fallback to `index.html` for client-side routing

### Environment Variables
```bash
DOMAIN=example.com              # Your base domain
NODE_ENV=production            # Environment mode
SITE_TITLE=TigerStyle Whiskers Documentation
SITE_DESCRIPTION=WordPress GDPR Compliance Plugin Documentation
```

## 📁 Project Structure

```
docs/
├── public/                    # Static assets
├── src/
│   ├── components/           # Astro components
│   │   └── AlpineInit.astro # Alpine.js initialization
│   ├── content/docs/        # Documentation content
│   └── assets/              # Images and other assets
├── astro.config.mjs         # Astro configuration
├── package.json             # Dependencies and scripts
├── Dockerfile               # Multi-stage Docker build
├── Caddyfile               # Caddy web server config
├── docker-compose.yml      # Container orchestration
└── .dockerignore           # Docker build exclusions
```

## 🚨 Troubleshooting

### Container Issues
```bash
# Check container logs
docker compose logs tigerstyle-whiskers-docs

# Verify Caddyfile syntax
docker run --rm -v $(pwd)/Caddyfile:/etc/caddy/Caddyfile caddy:2-alpine caddy validate --config /etc/caddy/Caddyfile

# Check health status
docker inspect tigerstyle-whiskers-docs --format '{{.State.Health.Status}}'
```

### Build Issues
```bash
# Clear npm cache
npm cache clean --force

# Remove node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Check Node.js version
node --version  # Should be 18+
```

### Deployment Issues
- Verify Caddy Docker Proxy network exists: `docker network ls`
- Check domain DNS configuration
- Ensure `DOMAIN` environment variable is set

## 📈 Performance Optimization

### Build Optimizations
- Tree-shaking for unused code elimination
- Minification of CSS and JavaScript
- Image optimization and responsive images
- Critical CSS inlining

### Serving Optimizations
- Caddy's efficient static file serving
- Gzip compression (6 levels)
- Browser caching headers
- CDN-ready static assets

## 🔧 Content Management

### Adding New Pages
1. Create Markdown/MDX file in appropriate `src/content/docs/` subdirectory
2. Add frontmatter with title and description
3. Update sidebar navigation in `astro.config.mjs` if needed
4. Build and test locally

### Interactive Components
Alpine.js stores in `src/components/AlpineInit.astro`:
- **Consent Demo**: Privacy banner simulation
- **Privacy Configurator**: Settings generator
- **Compliance Checker**: Audit checklist
- **Cookie Explorer**: Cookie category browser
- **Geographic Simulator**: Location-based compliance

## 🤝 Contributing to Documentation

1. Edit content in `src/content/docs/`
2. Test changes locally with `npm run dev`
3. Build and test production version with `npm run build && npm run preview`
4. Commit changes to version control

The documentation automatically rebuilds when the container is restarted.

## 🔗 Technical References

- [Astro Documentation](https://docs.astro.build/)
- [Starlight Documentation](https://starlight.astro.build/)
- [Alpine.js Documentation](https://alpinejs.dev/)
- [Caddy Documentation](https://caddyserver.com/docs/)
- [Docker Compose Documentation](https://docs.docker.com/compose/)