677 lines
15 KiB
Markdown
677 lines
15 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"
|
|
label: "Getting Started"
|
|
title: "Getting Started"
|
|
|
|
!!site.page src: "setup"
|
|
label: "Installation"
|
|
title: "Installation"
|
|
```
|
|
|
|
### Processing with V Code
|
|
|
|
```v
|
|
import incubaid.herolib.core.playbook
|
|
import incubaid.herolib.web.doctree.meta as site_module
|
|
import incubaid.herolib.ui.console
|
|
|
|
// Process HeroScript file
|
|
mut plbook := playbook.new(path: './site_config.heroscript')!
|
|
|
|
// Execute site configuration
|
|
site_module.play(mut plbook)!
|
|
|
|
// Access the configured site
|
|
mut mysite := site_module.get(name: 'my_docs')!
|
|
|
|
// Print available pages
|
|
for page in mysite.pages {
|
|
console.print_item('Page: "${page.src}" - "${page.title}"')
|
|
}
|
|
|
|
println('Site has ${mysite.pages.len} pages')
|
|
```
|
|
|
|
---
|
|
|
|
## API Reference
|
|
|
|
### Site Factory
|
|
|
|
Factory functions to create and retrieve site instances:
|
|
|
|
```v
|
|
// Create a new site
|
|
mut mysite := site_module.new(name: 'my_docs')!
|
|
|
|
// Get existing site
|
|
mut mysite := site_module.get(name: 'my_docs')!
|
|
|
|
// Check if site exists
|
|
if site_module.exists(name: 'my_docs') {
|
|
println('Site exists')
|
|
}
|
|
|
|
// Get all site names
|
|
site_names := site_module.list() // Returns []string
|
|
|
|
// Get default site (creates if needed)
|
|
mut default := site_module.default()!
|
|
```
|
|
|
|
### Site Object Structure
|
|
|
|
```v
|
|
@[heap]
|
|
pub struct Site {
|
|
pub mut:
|
|
doctree_path string // path to the export of the doctree site
|
|
config SiteConfig // Full site configuration
|
|
pages []Page // Array of pages
|
|
links []Link // Array of links
|
|
categories []Category // Array of categories
|
|
announcements []Announcement // Array of announcements (can be multiple)
|
|
imports []ImportItem // Array of imports
|
|
build_dest []BuildDest // Production build destinations
|
|
build_dest_dev []BuildDest // Development build destinations
|
|
}
|
|
```
|
|
|
|
### Accessing Pages
|
|
|
|
```v
|
|
// Access all pages
|
|
pages := mysite.pages // []Page
|
|
|
|
// Access specific page by index
|
|
page := mysite.pages[0]
|
|
|
|
// Page structure
|
|
pub struct Page {
|
|
pub mut:
|
|
src string // "collection:page_name" format (unique identifier)
|
|
label string // Display label in navigation
|
|
title string // Display title on page (extracted from markdown if empty)
|
|
description string // SEO metadata
|
|
draft bool // Hide from navigation if true
|
|
hide_title bool // Don't show title on page
|
|
hide bool // Hide page completely
|
|
category_id int // Optional category ID (0 = root level)
|
|
}
|
|
```
|
|
|
|
### Categories and Navigation
|
|
|
|
```v
|
|
// Access all categories
|
|
categories := mysite.categories // []Category
|
|
|
|
// Category structure
|
|
pub struct Category {
|
|
pub mut:
|
|
path string // e.g., "Getting Started" or "Operations/Daily"
|
|
collapsible bool = true
|
|
collapsed bool
|
|
}
|
|
|
|
// Generate sidebar navigation
|
|
sidebar := mysite.sidebar() // Returns SideBar
|
|
|
|
// Sidebar structure
|
|
pub struct SideBar {
|
|
pub mut:
|
|
my_sidebar []NavItem
|
|
}
|
|
|
|
pub type NavItem = NavDoc | NavCat | NavLink
|
|
|
|
pub struct NavDoc {
|
|
pub:
|
|
path string // path is $collection/$name without .md
|
|
label string
|
|
}
|
|
|
|
pub struct NavCat {
|
|
pub mut:
|
|
label string
|
|
collapsible bool = true
|
|
collapsed bool
|
|
items []NavItem // nested NavDoc/NavCat/NavLink
|
|
}
|
|
|
|
pub struct NavLink {
|
|
pub:
|
|
label string
|
|
href string
|
|
description string
|
|
}
|
|
|
|
// Example: iterate navigation
|
|
sidebar := mysite.sidebar()
|
|
for item in sidebar.my_sidebar {
|
|
match item {
|
|
NavDoc {
|
|
println('Page: ${item.label} (${item.path})')
|
|
}
|
|
NavCat {
|
|
println('Category: ${item.label} (${item.items.len} items)')
|
|
}
|
|
NavLink {
|
|
println('Link: ${item.label} -> ${item.href}')
|
|
}
|
|
}
|
|
}
|
|
|
|
// Print formatted sidebar
|
|
println(mysite.sidebar_str())
|
|
```
|
|
|
|
### Site Configuration
|
|
|
|
```v
|
|
@[heap]
|
|
pub struct SiteConfig {
|
|
pub mut:
|
|
// Core
|
|
name string
|
|
title string
|
|
description string
|
|
tagline string
|
|
favicon string
|
|
image string
|
|
copyright string
|
|
|
|
// URLs (Docusaurus)
|
|
url string // Full site URL
|
|
base_url string // Base path (e.g., "/" or "/docs/")
|
|
url_home string // Home page path
|
|
|
|
// SEO Metadata
|
|
meta_title string // SEO title override
|
|
meta_image string // OG image override
|
|
|
|
// Navigation & Footer
|
|
footer Footer
|
|
menu Menu
|
|
|
|
// Publishing
|
|
build_dest []BuildDest // Production destinations
|
|
build_dest_dev []BuildDest // Development destinations
|
|
|
|
// Imports
|
|
imports []ImportItem
|
|
}
|
|
|
|
pub struct BuildDest {
|
|
pub mut:
|
|
path string
|
|
ssh_name string
|
|
}
|
|
|
|
pub struct Menu {
|
|
pub mut:
|
|
title string
|
|
items []MenuItem
|
|
logo_alt string
|
|
logo_src string
|
|
logo_src_dark string
|
|
}
|
|
|
|
pub struct MenuItem {
|
|
pub mut:
|
|
href string
|
|
to string
|
|
label string
|
|
position string // "left" or "right"
|
|
}
|
|
|
|
pub struct Footer {
|
|
pub mut:
|
|
style string // e.g., "dark" or "light"
|
|
links []FooterLink
|
|
}
|
|
|
|
pub struct FooterLink {
|
|
pub mut:
|
|
title string
|
|
items []FooterItem
|
|
}
|
|
|
|
pub struct FooterItem {
|
|
pub mut:
|
|
label string
|
|
to string
|
|
href string
|
|
}
|
|
|
|
pub struct Announcement {
|
|
pub mut:
|
|
content string
|
|
background_color string
|
|
text_color string
|
|
is_closeable bool
|
|
}
|
|
|
|
pub struct ImportItem {
|
|
pub mut:
|
|
url string // http or git url
|
|
path string
|
|
dest string // location in docs folder
|
|
replace map[string]string
|
|
visible bool = true
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Core Concepts
|
|
|
|
### Site
|
|
A website configuration that contains pages, navigation structure, and metadata. Each site is registered globally and can be retrieved by name.
|
|
|
|
### Page
|
|
A single documentation page with:
|
|
- **src**: `collection:page_name` format (unique identifier)
|
|
- **label**: Display name in sidebar
|
|
- **title**: Display name on page (extracted from markdown if empty)
|
|
- **description**: SEO metadata
|
|
- **draft**: Hidden from navigation if true
|
|
- **category_id**: Links page to a category (0 = root level)
|
|
|
|
### Category (Section)
|
|
Groups related pages together in the navigation sidebar. Categories can be nested and are automatically collapsed/expandable.
|
|
|
|
```heroscript
|
|
!!site.page_category
|
|
path: "Getting Started"
|
|
collapsible: true
|
|
collapsed: false
|
|
|
|
!!site.page src: "tech:intro"
|
|
category_id: 1 // Links to the category above
|
|
```
|
|
|
|
### 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)
|
|
|
|
Multiple announcements are supported and stored in an array:
|
|
|
|
```heroscript
|
|
!!site.announcement
|
|
content: "🎉 Version 2.0 is now available!"
|
|
background_color: "#20232a"
|
|
text_color: "#fff"
|
|
is_closeable: true
|
|
```
|
|
|
|
**Note:** Each `!!site.announcement` block adds to the `announcements[]` array. Only the first is typically displayed, but all are stored.
|
|
|
|
### 6. Pages and Categories
|
|
|
|
#### Simple: Pages Without Categories
|
|
|
|
```heroscript
|
|
!!site.page src: "guides:introduction"
|
|
label: "Getting Started"
|
|
title: "Getting Started"
|
|
description: "Introduction to the platform"
|
|
|
|
!!site.page src: "installation"
|
|
label: "Installation"
|
|
title: "Installation"
|
|
```
|
|
|
|
#### Advanced: Pages With Categories
|
|
|
|
```heroscript
|
|
!!site.page_category
|
|
path: "Getting Started"
|
|
collapsible: true
|
|
collapsed: false
|
|
|
|
!!site.page src: "guides:introduction"
|
|
label: "Introduction"
|
|
title: "Introduction"
|
|
description: "Learn the basics"
|
|
|
|
!!site.page src: "installation"
|
|
label: "Installation"
|
|
title: "Installation"
|
|
|
|
!!site.page src: "configuration"
|
|
label: "Configuration"
|
|
title: "Configuration"
|
|
|
|
!!site.page_category
|
|
path: "Advanced Topics"
|
|
collapsible: true
|
|
collapsed: false
|
|
|
|
!!site.page src: "advanced:performance"
|
|
label: "Performance Tuning"
|
|
title: "Performance Tuning"
|
|
|
|
!!site.page src: "scaling"
|
|
label: "Scaling Guide"
|
|
title: "Scaling Guide"
|
|
```
|
|
|
|
**Page Parameters:**
|
|
- `src` - Source as `collection:page_name` (first page) or just `page_name` (reuse collection)
|
|
- `label` - Display label in sidebar (required)
|
|
- `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)
|
|
- `hide` - Hide page completely (default: false)
|
|
|
|
**Category Parameters:**
|
|
- `path` - Category path/label (required)
|
|
- `collapsible` - Allow collapsing (default: true)
|
|
- `collapsed` - Initially collapsed (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
|
|
path: "Getting Started"
|
|
collapsible: true
|
|
collapsed: false
|
|
|
|
!!site.page src: "docs:intro"
|
|
label: "Introduction"
|
|
title: "Introduction"
|
|
|
|
!!site.page src: "installation"
|
|
label: "Installation"
|
|
title: "Installation"
|
|
|
|
!!site.page_category
|
|
path: "Core Concepts"
|
|
collapsible: true
|
|
collapsed: false
|
|
|
|
!!site.page src: "concepts:architecture"
|
|
label: "Architecture"
|
|
title: "Architecture"
|
|
|
|
!!site.page src: "components"
|
|
label: "Components"
|
|
title: "Components"
|
|
|
|
!!site.page_category
|
|
path: "API Reference"
|
|
collapsible: true
|
|
collapsed: false
|
|
|
|
!!site.page src: "api:rest"
|
|
label: "REST API"
|
|
title: "REST API"
|
|
|
|
!!site.page src: "graphql"
|
|
label: "GraphQL"
|
|
title: "GraphQL"
|
|
```
|
|
|
|
### Pattern 2: Simple Blog/Knowledge Base
|
|
|
|
```heroscript
|
|
!!site.config
|
|
name: "blog"
|
|
title: "Knowledge Base"
|
|
|
|
!!site.page src: "articles:first_post"
|
|
label: "Welcome to Our Blog"
|
|
title: "Welcome to Our Blog"
|
|
|
|
!!site.page src: "second_post"
|
|
label: "Understanding the Basics"
|
|
title: "Understanding the Basics"
|
|
|
|
!!site.page src: "third_post"
|
|
label: "Advanced Techniques"
|
|
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
|
|
path: "Product Guide"
|
|
collapsible: true
|
|
collapsed: false
|
|
|
|
!!site.page src: "docs:overview"
|
|
label: "Overview"
|
|
title: "Overview"
|
|
|
|
!!site.page src: "features"
|
|
label: "Features"
|
|
title: "Features"
|
|
|
|
!!site.page_category
|
|
path: "Shared Resources"
|
|
collapsible: true
|
|
collapsed: false
|
|
|
|
!!site.page src: "shared:common"
|
|
label: "Common Patterns"
|
|
title: "Common Patterns"
|
|
```
|
|
|
|
---
|
|
|
|
## File Organization
|
|
|
|
### Recommended Ebook Structure
|
|
|
|
The modern ebook structure uses `.hero` files for configuration and `.heroscript` files for page definitions:
|
|
|
|
```
|
|
my_ebook/
|
|
├── scan.hero # !!doctree.scan - collection scanning
|
|
├── config.hero # !!site.config - site configuration
|
|
├── menus.hero # !!site.navbar and !!site.footer
|
|
├── include.hero # !!docusaurus.define and !!doctree.export
|
|
├── 1_intro.heroscript # Page definitions (categories + pages)
|
|
├── 2_concepts.heroscript # More page definitions
|
|
└── 3_advanced.heroscript # Additional pages
|
|
```
|
|
|
|
### File Types
|
|
|
|
- **`.hero` files**: Configuration files processed in any order
|
|
- **`.heroscript` files**: Page definition files processed alphabetically
|
|
|
|
Use numeric prefixes on `.heroscript` files to control page/category ordering in the sidebar.
|
|
|
|
### Example scan.hero
|
|
|
|
```heroscript
|
|
!!doctree.scan path:"../../collections/my_collection"
|
|
```
|
|
|
|
### Example include.hero
|
|
|
|
```heroscript
|
|
// Include shared configuration (optional)
|
|
!!play.include path:'../../heroscriptall' replace:'SITENAME:my_ebook'
|
|
|
|
// Or define directly
|
|
!!docusaurus.define name:'my_ebook'
|
|
|
|
!!doctree.export include:true
|
|
```
|
|
|
|
### Running an Ebook
|
|
|
|
```bash
|
|
# Development server
|
|
hero docs -d -p /path/to/my_ebook
|
|
|
|
# Build for production
|
|
hero docs -p /path/to/my_ebook
|
|
```
|