doit-ssg

Table of Contents

• 1. Overview
  • 1.1. Supported SSG Languages
• 2. Quick Start
  • 2.1. Prerequisites
  • 2.2. Installation
  • 2.3. Basic Usage
• 3. Project Structure
• 4. Adapters
  • 4.1. Adapter Commands
• 5. Development
  • 5.1. Task Runner
  • 5.2. Testing
  • 5.3. Security
• 6. Configuration
  • 6.1. SCM Files
  • 6.2. Environment Variables
• 7. Documentation
• 8. Roadmap
• 9. License
• 10. Acknowledgments
• 11. Contributing
• 12. Support

A satellite SSG (Static Site Generator) implementation in the hyperpolymath ecosystem, integrating with the poly-ssg-mcp hub to provide unified access to 28 static site generators across 14+ programming languages.

1. Overview

doit-ssg is a satellite project that consumes SSG adapters from the poly-ssg-mcp hub, providing a unified interface to build static sites using any of 28 supported generators.

1.1. Supported SSG Languages

Tier	Languages & SSGs
Tier 1	Rust (Zola, Cobalt, mdBook), Haskell (Hakyll, Ema), Elixir (Serum, NimblePublisher, Tableau)
Tier 2	Julia (Franklin, Documenter, StaticWebPages), Clojure (Cryogen, Perun, Babashka), Racket (Frog, Pollen), Scala (Laika, ScalaTex)
Tier 3	Kotlin (Orchid), F# (Fornax), OCaml (YOCaml), Nim (Nimrod), Crystal (Marmot), Swift (Publish), D (Reggae), Tcl (Wub), Erlang (Zotonic), Common Lisp (Coleslaw)

2. Quick Start

2.1. Prerequisites

• Deno runtime (v1.x+)

• just task runner

• Git

2.2. Installation

# Clone the repository
git clone https://github.com/hyperpolymath/doit-ssg.git
cd doit-ssg

# Verify setup
just status

# List available adapters
just adapters

2.3. Basic Usage

# Run all tests
just test

# Check adapter syntax
just check-syntax

# Verify adapter interface
just adapter-verify

# Full CI pipeline
just ci

3. Project Structure

doit-ssg/
├── adapters/           # 28 SSG adapters (synced from hub)
│   ├── zola.js
│   ├── hakyll.js
│   ├── cobalt.js
│   └── ... (28 total)
├── tests/              # Test suite
│   ├── adapters/       # Adapter tests
│   └── e2e/            # End-to-end tests
├── examples/           # Example configurations
│   ├── config/         # Sample configs
│   ├── templates/      # Sample templates
│   └── content/        # Sample content
├── docs/               # Documentation
│   └── api/            # API reference
├── .github/            # GitHub configuration
│   └── workflows/      # CI/CD pipelines
├── justfile            # Task automation
├── Mustfile            # Mandatory gates
├── cookbook.adoc       # CLI/Just/Nickel reference
├── META.scm            # Architecture decisions
├── ECOSYSTEM.scm       # Ecosystem position
├── STATE.scm           # Project state & roadmap
├── PLAYBOOK.scm        # Operational runbooks
├── AGENTIC.scm         # AI agent configuration
├── NEUROSYM.scm        # Neurosymbolic reasoning
└── flake.nix           # Nix development environment

4. Adapters

Each adapter provides a consistent interface to interact with an SSG:

// Adapter interface
export const name = "SSGName";
export const language = "Language";
export const description = "Brief description";

export async function connect() { /* ... */ }
export async function disconnect() { /* ... */ }
export function isConnected() { /* ... */ }

export const tools = [
  {
    name: "tool_name",
    description: "What the tool does",
    inputSchema: { /* JSON Schema */ },
    execute: async (params) => { /* ... */ }
  }
];

4.1. Adapter Commands

# List all adapters
just adapters

# Count adapters
just adapter-count

# Verify interface compliance
just adapter-verify

# Sync from hub
just adapter-sync

5. Development

5.1. Task Runner

This project uses just for task automation. See cookbook.adoc for complete reference.

# Show all commands
just --list

# Common workflows
just build          # Build all
just test           # Run tests
just lint           # Run linters
just ci             # Full CI pipeline

5.2. Testing

# Run all tests
just test-all

# Unit tests only
just test-unit

# E2E tests
just test-e2e

# Adapter tests
just test-adapters

5.3. Security

# Check for secrets
just check-secrets

# Security audit
just audit

# Full security check
just lint-security

6. Configuration

6.1. SCM Files

The project uses Scheme-based configuration files for metadata:

File	Purpose
META.scm	Architecture Decision Records (ADRs)
ECOSYSTEM.scm	Position in hyperpolymath ecosystem
STATE.scm	Current state and roadmap
PLAYBOOK.scm	Operational workflows and runbooks
AGENTIC.scm	AI agent behavior configuration
NEUROSYM.scm	Neurosymbolic reasoning patterns

6.2. Environment Variables

Variable	Default	Description
DENO_DIR	~/.cache/deno	Deno cache directory
NO_COLOR	unset	Disable colored output
DEBUG	unset	Enable debug logging

7. Documentation

• Contributing Guide

• Security Policy

• Code of Conduct

• Cookbook - CLI/Just/Nickel Reference

• API Documentation

8. Roadmap

See STATE.scm for the complete roadmap. Current milestones:

Version	Name	Status	Target
v0.1.0	Initial Setup	Complete	2025-12-15
v0.2.0	Build System & Automation	Complete	2025-12-24
v0.3.0	Testing & Quality	In Progress	2025-12-31
v0.4.0	MCP Integration	Planned	2026-01-15
v0.5.0	Nix & Reproducibility	Planned	2026-01-31
v1.0.0	Production Ready	Planned	2026-03-01

9. License

Dual licensed under:

• AGPL-3.0-or-later

• MIT (with Palimpsest License philosophical overlay)

10. Acknowledgments

• poly-ssg-mcp - Hub project providing adapters

• RSR - Repository standards

• All SSG maintainers for their excellent tools

11. Contributing

See CONTRIBUTING.md for guidelines.

12. Support

• GitHub Issues - Bug reports

• GitHub Discussions - Questions

• See SECURITY.md for security issues