...

2025-11-28 09:37:21 +01:00
parent fc13f3e6ae
commit 7c03226054
6 changed files with 835 additions and 260 deletions
--- a/examples/web/site/USAGE.md
+++ b/examples/web/site/USAGE.md
@@ -0,0 +1,201 @@
+# Site Module Usage Guide
+
+## Quick Examples
+
+### 1. Run Basic Example
+
+```bash
+cd examples/web/site
+vrun process_site.vsh ./
+```
+
+With output:
+```
+=== Site Configuration Processor ===
+Processing HeroScript files from: ./
+Found 1 HeroScript file(s):
+  - basic.heroscript
+
+Processing: basic.heroscript
+
+=== Configuration Complete ===
+Site: simple_docs
+Title: Simple Documentation
+Pages: 4
+Description: A basic documentation site
+Navigation structure:
+  - [Page] Getting Started
+  - [Page] Installation
+  - [Page] Usage Guide
+  - [Page] FAQ
+
+✓ Site configuration ready for deployment
+```
+
+### 2. Run Multi-Section Example
+
+```bash
+vrun process_site.vsh ./
+# Edit process_site.vsh to use multi_section.heroscript instead
+```
+
+### 3. Process Custom Directory
+
+```bash
+vrun process_site.vsh /path/to/your/site/config
+```
+
+## File Structure
+
+```
+docs/
+├── 0_config.heroscript     # Basic config
+├── 1_menu.heroscript       # Navigation
+├── 2_pages.heroscript      # Pages and categories
+└── process.vsh             # Your processing script
+```
+
+## Creating Your Own Site
+
+1. **Create a config directory:**
+   ```bash
+   mkdir my_site
+   cd my_site
+   ```
+
+2. **Create config file (0_config.heroscript):**
+   ```heroscript
+   !!site.config
+       name: "my_site"
+       title: "My Site"
+   ```
+
+3. **Create pages file (1_pages.heroscript):**
+   ```heroscript
+   !!site.page src: "docs:intro"
+       title: "Getting Started"
+   ```
+
+4. **Process with script:**
+   ```bash
+   vrun ../process_site.vsh ./
+   ```
+
+## Common Workflows
+
+### Workflow 1: Documentation Site
+
+```
+docs/
+├── 0_config.heroscript
+│   └── Basic config + metadata
+├── 1_menu.heroscript
+│   └── Navbar + footer
+├── 2_getting_started.heroscript
+│   └── Getting started pages
+├── 3_api.heroscript
+│   └── API reference pages
+└── 4_advanced.heroscript
+    └── Advanced topic pages
+```
+
+### Workflow 2: Internal Knowledge Base
+
+```
+kb/
+├── 0_config.heroscript
+├── 1_navigation.heroscript
+└── 2_articles.heroscript
+```
+
+### Workflow 3: Product Documentation with Imports
+
+```
+product_docs/
+├── 0_config.heroscript
+├── 1_imports.heroscript
+│   └── Import shared templates
+├── 2_menu.heroscript
+└── 3_pages.heroscript
+```
+
+## Tips & Tricks
+
+### Tip 1: Reuse Collections
+
+```heroscript
+# Specify once, reuse multiple times
+!!site.page src: "guides:intro"
+!!site.page src: "setup"        # Reuses "guides"
+!!site.page src: "deployment"   # Still "guides"
+
+# Switch to new collection
+!!site.page src: "api:reference"
+!!site.page src: "examples"     # Now "api"
+```
+
+### Tip 2: Auto-Increment Categories
+
+```heroscript
+# Automatically positioned at 100, 200, 300...
+!!site.page_category name: "basics"
+!!site.page_category name: "advanced"
+!!site.page_category name: "expert"
+
+# Or specify explicit positions
+!!site.page_category name: "basics" position: 10
+!!site.page_category name: "advanced" position: 20
+```
+
+### Tip 3: Title Extraction
+
+Let titles come from markdown files:
+
+```heroscript
+# Don't specify title
+!!site.page src: "docs:introduction"
+# Title will be extracted from # Heading in introduction.md
+```
+
+### Tip 4: Draft Pages
+
+Hide pages while working on them:
+
+```heroscript
+!!site.page src: "docs:work_in_progress"
+    draft: true
+    title: "Work in Progress"
+```
+
+## Debugging
+
+### Debug: Check What Got Configured
+
+```v
+mut s := site.get(name: 'my_site')!
+println(s.pages)        // All pages
+println(s.nav)          // Navigation structure
+println(s.siteconfig)   // Configuration
+```
+
+### Debug: List All Sites
+
+```v
+sites := site.list()
+for site_name in sites {
+    println('Site: ${site_name}')
+}
+```
+
+### Debug: Enable Verbose Output
+
+Add `console.print_debug()` calls in your HeroScript processing.
+
+## Next Steps
+
+- Customize `process_site.vsh` for your needs
+- Add your existing pages (in markdown)
+- Export to Docusaurus
+- Deploy to production
+
+For more info, see the main [Site Module README](./readme.md).
--- a/examples/web/site/basic.heroscript
+++ b/examples/web/site/basic.heroscript
@@ -0,0 +1,53 @@
+#!/usr/bin/env hero
+# Basic single-section documentation site
+
+!!site.config
+    name: "simple_docs"
+    title: "Simple Documentation"
+    description: "A basic documentation site"
+    copyright: "© 2024 Example"
+    url: "https://docs.example.com"
+    base_url: "/"
+
+!!site.navbar
+    title: "Simple Docs"
+    logo_src: "img/logo.png"
+
+!!site.navbar_item
+    label: "Docs"
+    to: "/"
+    position: "left"
+
+!!site.navbar_item
+    label: "GitHub"
+    href: "https://github.com/example/repo"
+    position: "right"
+
+!!site.footer
+    style: "dark"
+
+!!site.footer_item
+    title: "Documentation"
+    label: "Getting Started"
+    to: "getting-started"
+
+!!site.footer_item
+    title: "Community"
+    label: "Discord"
+    href: "https://discord.gg/example"
+
+!!site.page src: "docs:introduction"
+    title: "Getting Started"
+    description: "Learn the basics"
+
+!!site.page src: "installation"
+    title: "Installation"
+    description: "How to install"
+
+!!site.page src: "usage"
+    title: "Usage Guide"
+    description: "How to use the system"
+
+!!site.page src: "faq"
+    title: "FAQ"
+    description: "Frequently asked questions"
--- a/examples/web/site/multi_section.heroscript
+++ b/examples/web/site/multi_section.heroscript
@@ -0,0 +1,155 @@
+#!/usr/bin/env hero
+# Multi-section documentation with categories
+
+!!site.config
+    name: "multi_docs"
+    title: "Complete Documentation"
+    description: "Comprehensive documentation with multiple sections"
+    tagline: "Everything you need to know"
+    copyright: "© 2024 Tech Company"
+    url: "https://docs.techcompany.com"
+    base_url: "/docs"
+
+!!site.navbar
+    title: "Tech Documentation"
+    logo_src: "img/logo.svg"
+
+!!site.navbar_item
+    label: "Documentation"
+    to: "/"
+    position: "left"
+
+!!site.navbar_item
+    label: "API"
+    to: "api"
+    position: "left"
+
+!!site.navbar_item
+    label: "GitHub"
+    href: "https://github.com/techcompany"
+    position: "right"
+
+!!site.footer
+    style: "dark"
+
+!!site.footer_item
+    title: "Guides"
+    label: "Getting Started"
+    to: "getting-started"
+
+!!site.footer_item
+    title: "Guides"
+    label: "Installation"
+    to: "installation"
+
+!!site.footer_item
+    title: "Company"
+    label: "Website"
+    href: "https://techcompany.com"
+
+!!site.footer_item
+    title: "Legal"
+    label: "Privacy"
+    href: "https://techcompany.com/privacy"
+
+# ==================================================
+# Getting Started Section
+# ==================================================
+
+!!site.page_category
+    name: "getting_started"
+    label: "Getting Started"
+    position: 100
+
+!!site.page src: "docs:introduction"
+    title: "Introduction"
+    description: "What is this project?"
+
+!!site.page src: "installation"
+    title: "Installation"
+    description: "Get up and running"
+
+!!site.page src: "quickstart"
+    title: "Quick Start"
+    description: "Your first steps"
+
+# ==================================================
+# Core Concepts Section
+# ==================================================
+
+!!site.page_category
+    name: "concepts"
+    label: "Core Concepts"
+    position: 200
+
+!!site.page src: "concepts:architecture"
+    title: "Architecture"
+    description: "System design and architecture"
+
+!!site.page src: "components"
+    title: "Components"
+    description: "Main system components"
+
+!!site.page src: "data_flow"
+    title: "Data Flow"
+    description: "How data flows through the system"
+
+!!site.page src: "security"
+    title: "Security"
+    description: "Security considerations"
+
+# ==================================================
+# Advanced Topics Section
+# ==================================================
+
+!!site.page_category
+    name: "advanced"
+    label: "Advanced Topics"
+    position: 300
+
+!!site.page src: "advanced:performance"
+    title: "Performance Tuning"
+    description: "Optimize your system"
+
+!!site.page src: "scaling"
+    title: "Scaling"
+    description: "Scale to millions of users"
+
+!!site.page src: "deployment"
+    title: "Deployment"
+    description: "Deploy to production"
+
+# ==================================================
+# API Reference Section
+# ==================================================
+
+!!site.page_category
+    name: "api"
+    label: "API Reference"
+    position: 400
+
+!!site.page src: "api:overview"
+    title: "API Overview"
+    description: "API capabilities and base URLs"
+
+!!site.page src: "rest_api"
+    title: "REST API"
+    description: "Complete REST API documentation"
+
+!!site.page src: "graphql_api"
+    title: "GraphQL"
+    description: "GraphQL API documentation"
+
+!!site.page src: "webhooks"
+    title: "Webhooks"
+    description: "Implement webhooks in your app"
+
+# ==================================================
+# Publishing
+# ==================================================
+
+!!site.publish
+    path: "/var/www/html/docs"
+
+!!site.publish_dev
+    path: "/tmp/docs-preview"
--- a/examples/web/site/process_site.vsh
+++ b/examples/web/site/process_site.vsh
@@ -0,0 +1,116 @@
+#!/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
+import os
+
+// Process a site configuration from HeroScript files
+
+println(console.color_fg(.green) + '=== Site Configuration Processor ===' + console.reset())
+
+// Get directory from command line or use default
+mut config_dir := './docs'
+if os.args.len > 1 {
+	config_dir = os.args[1]
+}
+
+if !os.exists(config_dir) {
+	console.print_stderr('Error: Directory not found: ${config_dir}')
+	exit(1)
+}
+
+console.print_item('Processing HeroScript files from: ${config_dir}')
+
+// Find all heroscript files
+mut heroscript_files := []string{}
+entries := os.ls(config_dir) or {
+	console.print_stderr('Error reading directory: ${err}')
+	exit(1)
+}
+
+for entry in entries {
+	if entry.ends_with('.heroscript') {
+		heroscript_files << entry
+	}
+}
+
+// Sort files (to ensure numeric prefix order)
+heroscript_files.sort()
+
+if heroscript_files.len == 0 {
+	console.print_stderr('No .heroscript files found in ${config_dir}')
+	exit(1)
+}
+
+console.print_item('Found ${heroscript_files.len} HeroScript file(s):')
+for file in heroscript_files {
+	console.print_item('  - ${file}')
+}
+
+// Process each file
+mut site_names := []string{}
+for file in heroscript_files {
+	full_path := os.join_path(config_dir, file)
+	console.print_lf(1)
+	console.print_header('Processing: ${file}')
+
+	mut plbook := playbook.new(path: full_path) or {
+		console.print_stderr('Error loading ${file}: ${err}')
+		continue
+	}
+
+	site.play(mut plbook) or {
+		console.print_stderr('Error processing ${file}: ${err}')
+		continue
+	}
+}
+
+// Get all configured sites
+site_names = site.list()
+
+if site_names.len == 0 {
+	console.print_stderr('No sites were configured')
+	exit(1)
+}
+
+console.print_lf(2)
+console.print_green('=== Configuration Complete ===')
+
+// Display configured sites
+for site_name in site_names {
+	mut configured_site := site.get(name: site_name) or { continue }
+
+	console.print_header('Site: ${site_name}')
+	console.print_item('Title: ${configured_site.siteconfig.title}')
+	console.print_item('Pages: ${configured_site.pages.len}')
+	console.print_item('Description: ${configured_site.siteconfig.description}')
+
+	// Show pages organized by category
+	if configured_site.nav.my_sidebar.len > 0 {
+		console.print_item('Navigation structure:')
+		for nav_item in configured_site.nav.my_sidebar {
+			match nav_item {
+				site.NavDoc {
+					console.print_item('  - [Page] ${nav_item.label}')
+				}
+				site.NavCat {
+					console.print_item('  - [Category] ${nav_item.label}')
+					for sub_item in nav_item.items {
+						match sub_item {
+							site.NavDoc {
+								console.print_item('    - ${sub_item.label}')
+							}
+							else {}
+						}
+					}
+				}
+				else {}
+			}
+		}
+	}
+
+	console.print_lf(1)
+}
+
+println(console.color_fg(.green) + '✓ Site configuration ready for deployment' + console.reset())