Froggo

A high-performance static site generator and frontend server for Bloggo headless CMS.

✨ Features

• 🚀 Lightning Fast - Static site generation with intelligent E-tag caching
• 🎨 Easy Customization - Site configuration, custom pages, and branding without touching code
• 🔄 Smart Caching - Dependency-aware caching with automatic invalidation
• 📡 Webhook-Driven - Real-time content updates via Bloggo webhooks
• 🎯 On-Demand Generation - Pages generated on first request then cached
• 📱 Responsive Design - Mobile-first, accessible, and SEO-optimized
• 🔍 Search Functionality - Built-in search with pagination
• 📊 View Tracking - Post analytics with user agent capture
• 🛠️ Template System - Powerful Go templates with custom functions
• 🤖 SEO Optimized - Automatic sitemap, RSS feed, and schema.org markup

🚀 Quick Start

Prerequisites

• Go 1.23 or higher
• Bloggo CMS instance (for content management)

Installation

# Clone the repository
git clone https://github.com/Elagoht/froggo.git
cd froggo

# Copy example environment file
cp .env.example .env

# Edit .env with your configuration
nano .env

# Run
make run

Configuration

Edit .env with your Bloggo settings:

# Bloggo API Configuration
BLOGGO_URL=https://your-bloggo-instance.com/api
TRUSTED_FRONTEND_KEY=your-secret-key-here

# Webhook Authentication (optional)
WEBHOOK_AUTH_HEADER_NAME=x-webhook-secret
WEBHOOK_AUTH_HEADER_VALUE=your-webhook-secret-here

# Server Configuration
SERVER_PORT=3000
PAGE_SIZE=10

Site Customization

Configure your site details in customizations/config.json:

{
  "siteName": "Your Blog Name",
  "siteURL": "https://yourdomain.com",
  "description": "Your blog description for SEO",
  "footer": {
    "text": "Your Blog Name."
  }
}

Running

# Build and run
make run

# Or use development mode with hot reload
make dev

# See all available commands
make help

The server will start on http://localhost:3000

🎨 Customization System

Froggo makes customization easy through the customizations/ directory:

📁 Directory Structure

customizations/
├── config.json       # Site configuration (required)
├── pages.json       # Custom pages (optional)
├── logo.webp        # Your custom logo (optional)
├── favicon.ico      # Your custom favicon (optional)
├── robots.txt       # Custom robots.txt (optional)
└── templates/       # Custom page templates
    ├── about.html
    └── who-we-are.html

🎯 What You Can Customize

• Site Identity: Name, URL, description, footer text
• Custom Pages: About, contact, team pages with custom templates
• Branding: Logo, favicon, robots.txt
• Templates: Custom page layouts using Go templates
• SEO: Meta tags, structured data, sitemap, RSS feed

Example: Add an About page

1. Add to customizations/pages.json:

   {
     "pages": [
       {
         "path": "/about",
         "template": "about",
         "title": "About Us",
         "description": "Learn about our team"
       }
     ]
   }
   

2. Create customizations/templates/about.html

3. Visit /about - Your page is live!

📖 See docs/CUSTOMIZATIONS.md for complete instructions.

🛣️ Available Routes

Content Pages

• / - Homepage with latest posts and categories
• /posts - All posts with pagination
• /posts/{slug} - Individual post page
• /categories - All categories
• /categories/{slug} - Category page with posts
• /tags - All tags
• /tags/{slug} - Tag page with posts
• /authors - All authors
• /authors/{id} - Author page with posts

Interactive Features

• /search?q={query} - Search posts with pagination
• /sitemap.xml - Auto-generated sitemap
• /rss.xml - RSS feed for latest posts
• /robots.txt - SEO robots file (customizable)

API Endpoints

• GET /api/posts/views - Get view counts for multiple posts
• GET /api/posts/{slug}/views - Get view count for single post
• POST /webhooks/revalidate - Webhook for content updates

🎛️ Template System

Froggo uses Go's powerful html/template system with custom functions:

Available Template Functions

• {{markdown .Content}} - Render markdown as HTML
• {{absURL .SiteURL "/path"}} - Generate absolute URLs
• {{imageURL "path"}} - Generate image proxy URLs
• {{formatDate .Date}} - Format dates (e.g., "Jan 2, 2006")
• {{timeAgo .Date}} - Relative time (e.g., "2 hours ago")
• {{truncate .Text 100}} - Truncate text to N characters

Template Files

• templates/base.html - Base layout with navigation
• templates/index.html - Homepage template
• templates/posts/ - Post listing and single post templates
• templates/categories/ - Category page templates
• templates/tags/ - Tag page templates
• templates/authors/ - Author page templates
• templates/search.html - Search results template

⚙️ Development

Make Commands

make build      # Build the binary
make run        # Build and run the server
make dev        # Run in development mode
make prod       # Build optimized production binary
make clean      # Remove build artifacts
make install    # Install/update dependencies
make test       # Run tests
make fmt        # Format code
make setup      # Create .env from example

Project Structure

froggo/
├── cmd/                  # Command-line interface
├── internal/
│   ├── api/             # Bloggo API client
│   ├── cache/           # Caching system
│   ├── generator/       # Static site generator
│   ├── handlers/        # HTTP route handlers
│   └── templates/       # Template registry
├── templates/           # Main site templates
├── customizations/      # User customizations
├── fallbacks/          # Default assets (CSS, JS, images)
├── docs/               # Documentation
├── .cache/             # Generated content (runtime)
└── static/             # (Removed - assets now in fallbacks/)

Adding Custom Templates

1. Create template in customizations/templates/
2. Add page definition to customizations/pages.json
3. Template receives data: .Title, .Description, .SiteName, .SiteURL, .Year

Asset Management

• CSS/JS: Modified in fallbacks/ (served from /static/)
• Images: Use image proxy at /uploads/* for Bloggo images
• Custom Assets: Place in customizations/ to override defaults

🔧 Configuration Options

Environment Variables (.env)

• BLOGGO_URL - Bloggo API endpoint
• TRUSTED_FRONTEND_KEY - API authentication key
• SERVER_PORT - Server port (default: 3000)
• PAGE_SIZE - Posts per page (default: 10)
• WEBHOOK_AUTH_* - Webhook authentication

Site Configuration (customizations/config.json)

• siteName - Blog name used in titles and SEO
• siteURL - Full URL for canonical links
• description - Default site description
• footer.text - Footer copyright text

🚀 Deployment

Production Build

# Build optimized binary
make prod

# Run with production configuration
./froggo

Docker (Coming Soon)

# Dockerfile example (to be added)
FROM golang:1.23-alpine AS builder
WORKDIR /app
COPY . .
RUN make prod
FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/froggo .
CMD ["./froggo"]

Environment Variables for Production

• Set BLOGGO_URL to your Bloggo instance
• Configure TRUSTED_FRONTEND_KEY securely
• Use reverse proxy (nginx/caddy) for SSL termination
• Configure webhook endpoint for content updates

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow Go formatting standards (make fmt)
• Write tests for new features
• Update documentation for changes
• Ensure all templates are responsive and accessible

📚 Documentation

• Customizations Guide - Complete customization instructions
• API Documentation - API endpoints and usage
• Template Reference - Template functions and examples
• Deployment Guide - Production deployment

🐛 Troubleshooting

Common Issues

Pages not loading:

• Check Bloggo API connectivity
• Verify TRUSTED_FRONTEND_KEY is correct
• Check .cache/ directory permissions

Custom pages not showing:

• Ensure customizations/config.json exists and is valid JSON
• Check template files in customizations/templates/
• Restart server after configuration changes

Assets not loading:

• Verify fallback assets exist in fallbacks/
• Check .cache/static/ directory is created
• Clear browser cache

View counts not updating:

• Check webhook configuration in Bloggo
• Verify webhook endpoint is accessible
• Check logs for webhook processing errors

📄 License

GPL-3.0 - see LICENSE file for details

🙏 Acknowledgments

• Bloggo - Headless CMS backend
• Chi - HTTP router
• Go Templates - Template engine

---

Built with ❤️ for the Go community

Report Issues • Discussions • Releases