# Underpost Static Site Generator - Examples

This directory contains comprehensive examples and documentation for the Underpost Static Site Generator.

## Contents

### Documentation

- **[STATIC-GENERATOR-GUIDE.md](./STATIC-GENERATOR-GUIDE.md)** - Complete guide covering all features, best practices, and advanced usage patterns

### Configuration Examples

- **[static-config-example.json](./static-config-example.json)** - Fully documented configuration file template with all available options

### SSR Component Examples

- **[ssr-components/CustomPage.js](./ssr-components/CustomPage.js)** - Complete example of a custom landing page with:
  - Semantic HTML structure
  - Accessibility features
  - Responsive design
  - Progressive enhancement
  - Inline critical CSS
  - Interactive JavaScript

## Quick Start

### 1. Generate a Config Template

```bash
underpost static --generate-config ./my-static-config.json
```

This creates a template configuration file with all available options documented.

### 2. Customize Your Config

Edit the generated config file with your specific requirements:

```json
{
  "page": "./src/client/ssr/body/YourPage.js",
  "outputPath": "./dist/index.html",
  "metadata": {
    "title": "Your App Title",
    "description": "Your app description"
  }
}
```

### 3. Build Your Static Page

```bash
underpost static --config-file ./my-static-config.json
```

## Example Usage Scenarios

### Basic Static Page

```bash
underpost static \
  --page ./src/client/ssr/body/DefaultSplashScreen.js \
  --output-path ./dist/index.html \
  --title "My App"
```

### Landing Page with SEO

```bash
underpost static \
  --page ./examples/ssr-components/CustomPage.js \
  --output-path ./dist/landing.html \
  --title "Welcome to My App" \
  --description "The best app for your needs" \
  --keywords "app,solution,innovation" \
  --theme-color "#667eea" \
  --canonical-url "https://myapp.com"
```

### Complete Customization

Use the provided `static-config-example.json`:

```bash
# Copy the example
cp ./examples/static-config-example.json ./my-config.json

# Edit with your settings
nano ./my-config.json

# Build
underpost static --config-file ./my-config.json
```

## Available Examples

### 1. Complete Configuration Example

**File:** `static-config-example.json`

**What it demonstrates:**
- Complete metadata configuration
- Script injection (head and body)
- Stylesheet management
- Icon configuration
- SSR component inclusion
- Microdata/structured data
- Custom payload injection

**Use case:** Production-ready web application with full SEO and PWA support

### 2. Custom Landing Page Component

**File:** `ssr-components/CustomPage.js`

**What it demonstrates:**
- Hero section with call-to-action
- Feature showcase grid
- Content sections
- Contact form
- Footer with links
- Responsive design
- Accessibility features
- Progressive enhancement

**Use case:** Marketing landing page or product showcase

## Configuration Options Reference

### Metadata Options

```json
{
  "metadata": {
    "title": "Page title",
    "description": "SEO description",
    "keywords": ["keyword1", "keyword2"],
    "author": "Author name",
    "themeColor": "#ffffff",
    "canonicalURL": "https://example.com",
    "thumbnail": "https://example.com/image.png",
    "locale": "en-US",
    "siteName": "Site Name"
  }
}
```

### Script Options

```json
{
  "scripts": {
    "head": [
      {
        "src": "https://cdn.example.com/script.js",
        "async": true,
        "integrity": "sha384-...",
        "crossorigin": "anonymous"
      },
      {
        "content": "window.config = {};",
        "type": "text/javascript"
      }
    ],
    "body": [
      {
        "src": "/app.js",
        "type": "module",
        "defer": true
      }
    ]
  }
}
```

### Style Options

```json
{
  "styles": [
    { "href": "/main.css" },
    { "content": "body { margin: 0; }" },
    { "href": "/print.css", "media": "print" }
  ]
}
```

### Icon Options

```json
{
  "icons": {
    "favicon": "/favicon.ico",
    "appleTouchIcon": "/apple-touch-icon.png",
    "manifest": "/manifest.json",
    "additional": [
      {
        "rel": "icon",
        "type": "image/png",
        "sizes": "32x32",
        "href": "/favicon-32x32.png"
      }
    ]
  }
}
```

### Component Options

```json
{
  "headComponents": [
    "./src/client/ssr/head/Seo.js",
    "./src/client/ssr/head/Pwa.js"
  ],
  "bodyComponents": [
    "./src/client/ssr/body/Header.js"
  ]
}
```

### Structured Data (Microdata)

```json
{
  "microdata": [
    {
      "@context": "https://schema.org",
      "@type": "WebSite",
      "name": "My Site",
      "url": "https://example.com"
    }
  ]
}
```

## Common Use Cases

### 1. Simple Blog Post

```json
{
  "page": "./src/client/ssr/body/BlogPost.js",
  "outputPath": "./dist/blog/my-post.html",
  "metadata": {
    "title": "My Blog Post Title",
    "description": "Summary of the blog post",
    "author": "John Doe",
    "keywords": ["blogging", "tutorial"]
  },
  "microdata": [
    {
      "@context": "https://schema.org",
      "@type": "BlogPosting",
      "headline": "My Blog Post Title",
      "author": {
        "@type": "Person",
        "name": "John Doe"
      },
      "datePublished": "2024-01-01"
    }
  ]
}
```

### 2. E-commerce Product Page

```json
{
  "page": "./src/client/ssr/body/ProductPage.js",
  "outputPath": "./dist/products/widget.html",
  "metadata": {
    "title": "Premium Widget - Buy Now",
    "description": "High-quality widget with free shipping",
    "thumbnail": "https://shop.com/widget.jpg"
  },
  "microdata": [
    {
      "@context": "https://schema.org",
      "@type": "Product",
      "name": "Premium Widget",
      "offers": {
        "@type": "Offer",
        "price": "29.99",
        "priceCurrency": "USD"
      }
    }
  ]
}
```

### 3. Documentation Page

```json
{
  "page": "./src/client/ssr/body/DocsPage.js",
  "outputPath": "./dist/docs/index.html",
  "headComponents": [
    "./src/client/ssr/head/Seo.js"
  ],
  "styles": [
    { "href": "/docs/prism.css" },
    { "href": "/docs/docs.css" }
  ],
  "scripts": {
    "body": [
      { "src": "/docs/prism.js", "defer": true },
      { "src": "/docs/search.js", "defer": true }
    ]
  }
}
```

### 4. Multi-language Pages

```bash
# English version
underpost static --config-file ./config-en.json --lang en --dir ltr

# Spanish version
underpost static --config-file ./config-es.json --lang es --dir ltr

# Arabic version
underpost static --config-file ./config-ar.json --lang ar --dir rtl
```

## Best Practices

### 1. SEO Optimization

✅ Always include title, description, and keywords
✅ Use canonical URLs
✅ Add Open Graph metadata
✅ Include structured data (JSON-LD)
✅ Optimize images in metadata

### 2. Performance

✅ Minify HTML in production
✅ Use async/defer for scripts
✅ Inline critical CSS
✅ Optimize asset loading order

### 3. Accessibility

✅ Use semantic HTML
✅ Include ARIA labels
✅ Ensure keyboard navigation
✅ Test with screen readers

### 4. Progressive Enhancement

✅ Ensure content works without JavaScript
✅ Add interactive features progressively
✅ Test on various devices
✅ Provide fallbacks

## Advanced Techniques

### Custom SSR Component Template

```javascript
/**
 * Custom Component Template
 * @description Brief description of the component
 */
SrrComponent = () => html`
  <div class="custom-component">
    <!-- Your HTML here -->
  </div>
  
  <style>
    /* Component-specific styles */
  </style>
  
  <script>
    // Component-specific JavaScript
    document.addEventListener('DOMContentLoaded', function() {
      // Your code here
    });
  </script>
`;
```

### Programmatic Usage

```javascript
import UnderpostStatic from './src/cli/static.js';

// Generate multiple pages
const pages = [
  { slug: 'home', title: 'Home' },
  { slug: 'about', title: 'About' },
  { slug: 'contact', title: 'Contact' }
];

for (const page of pages) {
  await UnderpostStatic.API.callback({
    page: `./src/client/ssr/body/${page.slug}.js`,
    outputPath: `./dist/${page.slug}.html`,
    metadata: {
      title: page.title
    }
  });
}
```

## Troubleshooting

### Component Not Found

**Error:** `Page component does not exist`

**Solution:** Verify the path is correct and the file exists

### Invalid JSON

**Error:** `Error loading config file: Unexpected token`

**Solution:** Validate your JSON using a linter or online validator

### Missing Metadata

**Warning:** No metadata generated

**Solution:** Ensure metadata object is properly configured in your config

## Getting Help

- Read the [Complete Guide](./STATIC-GENERATOR-GUIDE.md)
- Check the [example config](./static-config-example.json)
- Review the [custom page example](./ssr-components/CustomPage.js)
- Check the main project documentation

## Contributing

To add new examples:

1. Create your example file
2. Add comprehensive comments
3. Update this README
4. Test your example thoroughly
5. Submit a pull request

## License

Part of the Underpost framework. See main project license.