# Site Module

The Site module provides a structured way to define website configurations, navigation menus, pages, and sections using HeroScript. It's designed to work with static site generators like Docusaurus.


## Quick Start

### Minimal HeroScript Example

```heroscript
!!site.config
    name: "my_docs"
    title: "My Documentation"

!!site.page src: "docs:introduction"
    title: "Getting Started"

!!site.page src: "setup"
    title: "Installation"
```

### Processing with V Code

```v
#!/usr/bin/env -S v -n -w -gc none -cg -cc tcc -d use_openssl -enable-globals run

import incubaid.herolib.core.playbook
import incubaid.herolib.web.site
import incubaid.herolib.ui.console

// Process HeroScript file
mut plbook := playbook.new(path: './site_config.heroscript')!

// Execute site configuration
site.play(mut plbook)!

// Access the configured site
mut mysite := site.get(name: 'my_docs')!

// Print available pages
pages_map := mysite.list_pages()
for page_id, _ in pages_map {
    console.print_item('Page: ${page_id}')
}

println('Site has ${mysite.pages.len} pages')
```

---

## Core Concepts

### Site
A website configuration that contains pages, navigation structure, and metadata.

### Page
A single page with:
- **ID**: `collection:page_name` format
- **Title**: Display name (optional - extracted from markdown if not provided)
- **Description**: SEO metadata
- **Draft**: Hidden from navigation if true

### Category (Section)
Groups related pages together in the navigation sidebar. Automatically collapsed/expandable.

### Collection
A logical group of pages. Pages reuse the collection once specified.

```heroscript
!!site.page src: "tech:intro"          # Specifies collection "tech"
!!site.page src: "benefits"             # Reuses collection "tech" 
!!site.page src: "components"           # Still uses collection "tech"
!!site.page src: "api:reference"       # Switches to collection "api"
!!site.page src: "endpoints"            # Uses collection "api"
```

---

## HeroScript Syntax

### 1. Site Configuration (Required)

```heroscript
!!site.config
    name: "my_site"
    title: "My Documentation Site"
    description: "Comprehensive documentation"
    tagline: "Your awesome documentation"
    favicon: "img/favicon.png"
    image: "img/site-image.png"
    copyright: "© 2024 My Organization"
    url: "https://docs.example.com"
    base_url: "/"
    url_home: "/docs"
```

**Parameters:**
- `name` - Internal site identifier (default: 'default')
- `title` - Main site title (shown in browser tab)
- `description` - Site description for SEO
- `tagline` - Short tagline/subtitle
- `favicon` - Path to favicon image
- `image` - Default OG image for social sharing
- `copyright` - Copyright notice
- `url` - Full site URL for Docusaurus
- `base_url` - Base URL path (e.g., "/" or "/docs/")
- `url_home` - Home page path

### 2. Metadata Overrides (Optional)

```heroscript
!!site.config_meta
    title: "My Docs - Technical Reference"
    image: "img/tech-og.png"
    description: "Technical documentation and API reference"
```

Overrides specific metadata for SEO without changing core config.

### 3. Navigation Bar

```heroscript
!!site.navbar
    title: "My Documentation"
    logo_alt: "Site Logo"
    logo_src: "img/logo.svg"
    logo_src_dark: "img/logo-dark.svg"

!!site.navbar_item
    label: "Documentation"
    to: "intro"
    position: "left"

!!site.navbar_item
    label: "API Reference"
    to: "docs/api"
    position: "left"

!!site.navbar_item
    label: "GitHub"
    href: "https://github.com/myorg/myrepo"
    position: "right"
```

**Parameters:**
- `label` - Display text (required)
- `to` - Internal link
- `href` - External URL
- `position` - "left" or "right" in navbar

### 4. Footer Configuration

```heroscript
!!site.footer
    style: "dark"

!!site.footer_item
    title: "Docs"
    label: "Introduction"
    to: "intro"

!!site.footer_item
    title: "Docs"
    label: "Getting Started"
    to: "getting-started"

!!site.footer_item
    title: "Community"
    label: "Discord"
    href: "https://discord.gg/example"

!!site.footer_item
    title: "Legal"
    label: "Privacy"
    href: "https://example.com/privacy"
```

### 5. Announcement Bar (Optional)

```heroscript
!!site.announcement
    id: "new-release"
    content: "🎉 Version 2.0 is now available!"
    background_color: "#20232a"
    text_color: "#fff"
    is_closeable: true
```

### 6. Pages and Categories

#### Simple: Pages Without Categories

```heroscript
!!site.page src: "guides:introduction"
    title: "Getting Started"
    description: "Introduction to the platform"

!!site.page src: "installation"
    title: "Installation"

!!site.page src: "configuration"
    title: "Configuration"
```

#### Advanced: Pages With Categories

```heroscript
!!site.page_category
    name: "basics"
    label: "Getting Started"

!!site.page src: "guides:introduction"
    title: "Introduction"
    description: "Learn the basics"

!!site.page src: "installation"
    title: "Installation"

!!site.page src: "configuration"
    title: "Configuration"

!!site.page_category
    name: "advanced"
    label: "Advanced Topics"

!!site.page src: "advanced:performance"
    title: "Performance Tuning"

!!site.page src: "scaling"
    title: "Scaling Guide"
```

**Page Parameters:**
- `src` - Source as `collection:page` (first page) or just `page_name` (reuse collection)
- `title` - Page title (optional, extracted from markdown if not provided)
- `description` - Page description
- `draft` - Hide from navigation (default: false)
- `hide_title` - Don't show title in page (default: false)

### 7. Content Imports

```heroscript
!!site.import
    url: "https://github.com/example/external-docs"
    path: "/local/path/to/repo"
    dest: "external"
    replace: "PROJECT_NAME:My Project,VERSION:1.0.0"
    visible: true
```

### 8. Publishing Destinations

```heroscript
!!site.publish
    path: "/var/www/html/docs"
    ssh_name: "production"

!!site.publish_dev
    path: "/tmp/docs-preview"
```

---

## Common Patterns

### Pattern 1: Multi-Section Technical Documentation

```heroscript
!!site.config
    name: "tech_docs"
    title: "Technical Documentation"

!!site.page_category
    name: "getting_started"
    label: "Getting Started"

!!site.page src: "docs:intro"
    title: "Introduction"

!!site.page src: "installation"
    title: "Installation"

!!site.page_category
    name: "concepts"
    label: "Core Concepts"

!!site.page src: "concepts:architecture"
    title: "Architecture"

!!site.page src: "components"
    title: "Components"

!!site.page_category
    name: "api"
    label: "API Reference"

!!site.page src: "api:rest"
    title: "REST API"

!!site.page src: "graphql"
    title: "GraphQL"
```

### Pattern 2: Simple Blog/Knowledge Base

```heroscript
!!site.config
    name: "blog"
    title: "Knowledge Base"

!!site.page src: "articles:first_post"
    title: "Welcome to Our Blog"

!!site.page src: "second_post"
    title: "Understanding the Basics"

!!site.page src: "third_post"
    title: "Advanced Techniques"
```

### Pattern 3: Project with External Imports

```heroscript
!!site.config
    name: "project_docs"
    title: "Project Documentation"

!!site.import
    url: "https://github.com/org/shared-docs"
    dest: "shared"
    visible: true

!!site.page_category
    name: "product"
    label: "Product Guide"

!!site.page src: "docs:overview"
    title: "Overview"

!!site.page src: "features"
    title: "Features"

!!site.page_category
    name: "resources"
    label: "Shared Resources"

!!site.page src: "shared:common"
    title: "Common Patterns"
```

---

## File Organization

Organize HeroScript files with numeric prefixes to control execution order:

```
docs/
├── 0_config.heroscript
│   └── !!site.config and !!site.config_meta
│
├── 1_menu.heroscript
│   └── !!site.navbar and !!site.footer
│
├── 2_pages.heroscript
│   └── !!site.page_category and !!site.page actions
│
└── 3_publish.heroscript
    └── !!site.publish destinations
```

**Why numeric prefixes?**

Files are processed in alphabetical order. Numeric prefixes ensure:
- Site config runs first
- Navigation menu configures before pages
- Pages build the final structure
- Publishing configured last

---

## Processing Order

The Site module processes HeroScript in this strict order:

1. Site Configuration
2. Metadata Overrides
3. Imports
4. Navigation
5. Footer
6. Announcement
7. Publishing
8. Pages & Categories

Each stage depends on previous stages completing successfully.