396 lines
8.4 KiB
Markdown
396 lines
8.4 KiB
Markdown
# 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.
|