# Configuration Guide

This guide covers all configuration options available in vibe-seo.

## Configuration File

The main configuration file is `seo/config/seo.config.yaml`. This file is automatically created when you run `vibe-seo-init`.

## Configuration Structure

### Basic Site Information

```yaml
site:
  url: "https://yoursite.com"           # Your site's base URL (required)
  name: "Your Site Name"                # Site name for meta tags (required)
  description: "Your site description"  # Default meta description
  logo: "/assets/logo.png"             # Path to your logo
  language: "en"                       # Primary language code
  locale: "en_US"                      # Locale for Open Graph
  author: "author-name"            # Default author
  favicon: "/favicon.ico"              # Favicon path
```

### Framework Configuration

```yaml
framework: nextjs                      # Auto-detected framework
# Options: nextjs, nextjs-app, nextjs-pages, react, vue, angular, static
```

### Bot Configuration

```yaml
bots:
  allow:                              # Allowed crawlers
    - "Googlebot"                     # Google search
    - "Bingbot"                       # Microsoft Bing
    - "GPTBot"                        # OpenAI ChatGPT
    - "PerplexityBot"                 # Perplexity AI
    - "ClaudeBot"                     # Anthropic Claude
    - "Meta-ExternalAgent"            # Meta AI
    - "Applebot"                      # Apple Intelligence
    - "YouBot"                        # You.com
    - "DuckDuckBot"                   # DuckDuckGo
  disallow: []                        # Blocked crawlers
  crawlDelay: 1                       # Delay between requests (seconds)
```

### SEO Templates

```yaml
seo:
  titleTemplate: "{title} | {siteName}"           # Page title template
  descriptionTemplate: "{description}"            # Meta description template
  imageTemplate: "{siteUrl}/og-images/{slug}.png" # Open Graph image template
  twitterCard: "summary_large_image"              # Twitter card type
  ogType: "website"                               # Default Open Graph type
```

### Sitemap Configuration

```yaml
sitemap:
  changefreq: "weekly"                # Default change frequency
  priority: 0.8                       # Default priority
  excludePaths:                       # Paths to exclude from sitemap
    - "/admin/*"
    - "/api/*"
    - "/_next/*"
    - "/private/*"
```

### Verification Tokens

```yaml
verification:
  google: ""                          # Google Search Console verification
  bing: ""                            # Bing Webmaster Tools verification
  yandex: ""                          # Yandex Webmaster verification
  pinterest: ""                       # Pinterest verification
```

### Framework-Specific Paths

```yaml
paths:
  pagesDir: "./pages"                 # Pages directory (Next.js)
  appDir: "./app"                     # App directory (Next.js 13+)
  srcDir: "./src"                     # Source directory
  publicDir: "./public"               # Public assets directory
  outputDir: "./public"               # SEO files output directory
```

## Template Variables

### Available Variables

| Variable | Description | Example |
|----------|-------------|---------|
| `{title}` | Page title | "About Us" |
| `{siteName}` | Site name from config | "My Company" |
| `{description}` | Page description | "Learn about our company" |
| `{url}` | Page URL path | "/about" |
| `{siteUrl}` | Full site URL | "https://example.com" |
| `{slug}` | URL slug | "about-us" |

### Template Examples

```yaml
# Custom title template
titleTemplate: "{title} - {siteName} | Best Company Ever"

# Custom description template
descriptionTemplate: "{description} Visit {siteName} to learn more!"

# Custom Open Graph image template
imageTemplate: "{siteUrl}/images/og/{slug}-social.jpg"
```

## Framework-Specific Configuration

### Next.js

```yaml
framework: nextjs
paths:
  pagesDir: "./pages"      # For Pages Router
  appDir: "./app"          # For App Router (13+)
  publicDir: "./public"
  outputDir: "./public"
```

### React

```yaml
framework: react
paths:
  srcDir: "./src"
  publicDir: "./public"
  buildDir: "./build"
  outputDir: "./public"
```

### Vue

```yaml
framework: vue
paths:
  srcDir: "./src"
  publicDir: "./public"
  distDir: "./dist"
  outputDir: "./public"
```

### Angular

```yaml
framework: angular
paths:
  srcDir: "./src"
  distDir: "./dist"
  assetsDir: "./src/assets"
  outputDir: "./src"
```

### Static Sites

```yaml
framework: static
paths:
  srcDir: "./src"
  publicDir: "./public"
  outputDir: "./public"
```

## Advanced Configuration

### Custom Bot Rules

```yaml
bots:
  allow:
    - "Googlebot"
  disallow:
    - "BadBot"
  crawlDelay: 2
  
  # Custom rules per bot (advanced)
  customRules:
    "GPTBot":
      allow: ["/", "/docs/*"]
      disallow: ["/private/*"]
      crawlDelay: 1
```

### Multiple Sitemaps

```yaml
additionalSitemaps:
  - "https://yoursite.com/blog-sitemap.xml"
  - "https://yoursite.com/products-sitemap.xml"
```

### Environment-Specific Configuration

```yaml
# Use environment variables
site:
  url: "${SITE_URL}"
  name: "${SITE_NAME}"
verification:
  google: "${GOOGLE_VERIFICATION}"
```

## Validation

vibe-seo validates your configuration and will show helpful error messages:

```bash
# Check configuration
npx vibe-seo-gen scan
```

Common validation errors:

- Missing required fields (`site.url`, `site.name`)
- Invalid URL format
- Invalid bot names
- Missing framework paths

## Best Practices

1. **Always set site.url and site.name** - These are required for proper SEO
2. **Use environment variables** for sensitive data like verification tokens
3. **Exclude private paths** from sitemaps using `excludePaths`
4. **Set appropriate crawl delays** to be respectful to crawlers
5. **Use descriptive templates** that include your brand name
6. **Keep verification tokens secure** and don't commit them to version control

## Troubleshooting

### Configuration not loading

```bash
# Check if file exists and is valid YAML
npx vibe-seo-gen scan -c ./seo/config/seo.config.yaml
```

### Pages not detected

```bash
# See what pages are detected
npx vibe-seo-gen scan
```

### Invalid framework detection

```bash
# Force a specific framework
npx vibe-seo-init -f nextjs --force
```