|
1 | 1 | --- |
2 | | -title: Poly SSG - One Contract, Many Paradigms |
3 | | -description: Polyglot static site generator framework where each engine embodies its language's philosophy |
| 2 | +title: poly-ssg - Polyglot Static Site Generator Metaframework |
| 3 | +description: MCP-native metaframework for building and managing polyglot static site generators with formal verification |
| 4 | +date: 2026-01-30 |
| 5 | +license: PMPL-1.0-or-later |
4 | 6 | --- |
5 | 7 |
|
6 | | -# Poly SSG |
| 8 | +# poly-ssg |
7 | 9 |
|
8 | | -_One contract. Many paradigms. Every paradigm teaches._ |
| 10 | +**Polyglot Static Site Generator Metaframework** |
9 | 11 |
|
10 | | -A polyglot static site generator framework where each engine embodies its language's philosophy—from dependently-typed correctness to stack-based minimalism—unified through a common MCP interface. |
| 12 | + |
| 13 | + |
11 | 14 |
|
12 | | -## Who Is This For? |
| 15 | +A metaframework for building and managing polyglot static site generators with MCP (Model Context Protocol) integration and formal verification capabilities. |
13 | 16 |
|
14 | | -- **Paradigm explorers** — See the same problem solved through functional, logic, parallel, and stack-based lenses |
15 | | -- **Language enthusiasts** — Each engine is idiomatic, not a transliteration |
16 | | -- **MCP practitioners** — Switch between engines without changing your tooling |
17 | | -- **Educators** — Demonstrate that there's no "one true way" to generate sites |
| 17 | +## Philosophy |
18 | 18 |
|
19 | | -## Why poly-ssg? |
| 19 | +**poly-ssg** embraces the palimpsest nature of knowledge systems. Like manuscript layers building upon each other, static site generators should compose, interoperate, and preserve lineage across language boundaries. |
20 | 20 |
|
21 | | -### Paradigm Purity |
| 21 | +Traditional SSG ecosystems are siloed by language. poly-ssg breaks these barriers by: |
22 | 22 |
|
23 | | -Each engine embraces its language's strengths. Haskell stays pure. Prolog stays declarative. Forth stays stack-oriented. No lowest-common-denominator compromises. |
| 23 | +- **Language-agnostic orchestration** - Coordinate generators written in any language |
| 24 | +- **Formal verification hooks** - Integrate proof systems (a2ml, k9-svc) at build time |
| 25 | +- **MCP-native design** - First-class Model Context Protocol support |
| 26 | +- **Provenance preservation** - Track content lineage across transformations |
24 | 27 |
|
25 | | -### One Contract, Many Implementations |
| 28 | +## Current Engines |
26 | 29 |
|
27 | | -The MCP contract defines _what_ an SSG does. Each engine decides _how_. Your AI assistant, build scripts, and workflows remain unchanged when you switch paradigms. |
| 30 | +### Casket-SSG (Reference Implementation) ✓ |
28 | 31 |
|
29 | | -### Production-Ready Satellites |
| 32 | +**Language:** Haskell |
| 33 | +**Status:** Production Ready (v2.0.0) |
| 34 | +**Repository:** [hyperpolymath/casket-ssg](https://github.com/hyperpolymath/casket-ssg) |
30 | 35 |
|
31 | | -Each engine is a standalone project. **Use Casket (Haskell) in production** while exploring Ddraig (Idris 2) for provable correctness. They share a contract, not a codebase. |
| 36 | +First SSG with formal verification integration. Features: |
32 | 37 |
|
33 | | -## Engines |
| 38 | +- Markdown, AsciiDoc, RST, Org-mode support (via Pandoc) |
| 39 | +- a2ml integration (typed, verifiable markup) |
| 40 | +- k9-svc validation (self-validating components) |
| 41 | +- Spell checking (hunspell/aspell) |
| 42 | +- i18n support (en, es, fr, de) |
| 43 | +- Gnosis metadata integration |
34 | 44 |
|
35 | | -| Engine | Language | Paradigmatic Strength | Status | |
36 | | -|--------|----------|----------------------|--------| |
37 | | -| **Casket** | Haskell | Pure functional, a2ml + k9-svc verification | ✅ **Production (v1.0)** | |
38 | | -| **Ddraig** | Idris 2 | Dependently-typed, compile-time proofs | 🔧 In Development | |
39 | | -| **Estate** | Forth | Stack-based, minimal dependencies | 🔧 In Development | |
40 | | -| **Parallax** | Chapel | Data-parallel, massive scale | 🔧 In Development | |
41 | | -| **Prodigy** | Prolog | Logic-based, declarative rules | 🔧 In Development | |
42 | | -| **Rescribe** | ReScript | Type-safe JS compilation | 🔧 In Development | |
43 | | -| **Zigzag** | Zig | Zero-overhead, explicit control | 🔧 In Development | |
| 45 | +**Deployed sites:** |
| 46 | +- [axel-protocol.org](https://axel-protocol.org) |
| 47 | +- [stamp-protocol.org](https://stamp-protocol.org) |
| 48 | +- [asdf-plugins registry](https://hyperpolymath.github.io/asdf-plugins/) |
44 | 49 |
|
45 | | -## Casket SSG - First Production Engine |
| 50 | +### Planned Engines |
46 | 51 |
|
47 | | -**casket-ssg v1.0** is **production-ready** and powers this site! |
| 52 | +- **hackenbush-ssg** (ReScript) - Fast, type-safe with JSX templating |
| 53 | +- **bunsenite-ssg** (Nickel) - Configuration-as-code with type inference |
| 54 | +- **cobalt-ssg** (Rust) - Low-latency with incremental builds |
48 | 55 |
|
49 | | -### Features |
| 56 | +## MCP Integration |
50 | 57 |
|
51 | | -- ✅ Markdown & a2ml content formats |
52 | | -- ✅ YAML frontmatter |
53 | | -- ✅ External template system |
54 | | -- ✅ Asset pipeline (CSS, images auto-copy) |
55 | | -- ✅ Site configuration (config.yaml) |
56 | | -- ✅ **a2ml integration** (typed, verifiable markup) |
57 | | -- ✅ **k9-svc validation** (self-validating components) |
| 58 | +poly-ssg provides a unified MCP server interface: |
58 | 59 |
|
59 | | -**Unique:** First SSG with **formal verification** built-in. |
| 60 | +```javascript |
| 61 | +// Query any engine through MCP |
| 62 | +const result = await mcp.call("poly-ssg/build", { |
| 63 | + engine: "casket-ssg", |
| 64 | + input: "content/", |
| 65 | + output: "_site/" |
| 66 | +}); |
| 67 | +``` |
| 68 | + |
| 69 | +Engines register capabilities (Markdown, AsciiDoc, i18n, etc.) and poly-ssg routes requests to the appropriate implementation. |
| 70 | + |
| 71 | +## Formal Verification |
| 72 | + |
| 73 | +poly-ssg engines can integrate verification systems: |
| 74 | + |
| 75 | +- **a2ml** - Attested Markup Language with type-level content guarantees |
| 76 | +- **k9-svc** - Self-Validating Components with runtime proofs |
| 77 | +- **Idris2** - Dependent types for provable correctness |
60 | 78 |
|
61 | | -### Quick Start |
| 79 | +Example from Casket-SSG: |
| 80 | + |
| 81 | +```haskell |
| 82 | +-- Verify content compiles with a2ml type checker |
| 83 | +verifyContent :: A2MLDoc -> Either TypeError HTML |
| 84 | +``` |
| 85 | + |
| 86 | +## Use Cases |
| 87 | + |
| 88 | +- **Multi-engine sites** - Use Casket for formal content, hackenbush for blogs |
| 89 | +- **Proof-carrying content** - Mathematical papers with verified theorems |
| 90 | +- **Compliance documentation** - Generate sites with provable properties |
| 91 | +- **Research artifacts** - Preserve lineage and attribution chains |
| 92 | + |
| 93 | +## License |
| 94 | + |
| 95 | +**PMPL-1.0-or-later** (Palimpsest-MPL License) |
| 96 | + |
| 97 | +Like a palimpsest manuscript, poly-ssg recognizes that static site generators carry layers of meaning - from original content to transformation logic to final presentation. This license protects both technical attribution and cultural context. |
| 98 | + |
| 99 | +See the [Palimpsest License](https://github.com/hyperpolymath/palimpsest-license) for full details. |
| 100 | + |
| 101 | +### Why PMPL for poly-ssg? |
| 102 | + |
| 103 | +- **Emotional lineage** - Content transformations preserve author intent |
| 104 | +- **Quantum-safe provenance** - Long-term attribution for generated sites |
| 105 | +- **Ethical use framework** - Respect cultural and narrative context |
| 106 | +- **AI training permitted** - With clear attribution obligations |
| 107 | + |
| 108 | +## Getting Started |
| 109 | + |
| 110 | +### Using Casket-SSG (Available Now) |
62 | 111 |
|
63 | 112 | ```bash |
64 | | -# Clone casket-ssg |
| 113 | +# Clone the reference implementation |
65 | 114 | git clone https://github.com/hyperpolymath/casket-ssg |
66 | 115 | cd casket-ssg |
67 | 116 |
|
68 | 117 | # Build |
69 | | -stack build |
| 118 | +cabal build |
70 | 119 |
|
71 | | -# Build your site |
72 | | -casket-ssg build content _site |
| 120 | +# Generate a site |
| 121 | +cabal run casket-ssg build content/ _site/ |
73 | 122 | ``` |
74 | 123 |
|
75 | | -## Quick Links |
| 124 | +### Contributing an Engine |
76 | 125 |
|
77 | | -- [casket-ssg Repository](https://github.com/hyperpolymath/casket-ssg) |
78 | | -- [poly-ssg-mcp (MCP Interface)](https://github.com/hyperpolymath/poly-ssg-mcp) |
79 | | -- [Example Site: axel-protocol.org](https://axel-protocol.org) (Built with casket-ssg) |
80 | | -- [Contributing](https://github.com/hyperpolymath/poly-ssg/blob/main/CONTRIBUTING.adoc) |
| 126 | +See [ENGINE-SPEC.adoc](https://github.com/hyperpolymath/poly-ssg/blob/main/ENGINE-SPEC.adoc) for requirements. |
81 | 127 |
|
82 | | -## License |
| 128 | +## Resources |
83 | 129 |
|
84 | | -MPL-2.0-or-later | Philosophy: [Palimpsest](https://github.com/hyperpolymath/palimpsest-license) |
| 130 | +- **Repository:** [github.com/hyperpolymath/poly-ssg](https://github.com/hyperpolymath/poly-ssg) |
| 131 | +- **Casket-SSG:** [github.com/hyperpolymath/casket-ssg](https://github.com/hyperpolymath/casket-ssg) |
| 132 | +- **License:** [github.com/hyperpolymath/palimpsest-license](https://github.com/hyperpolymath/palimpsest-license) |
| 133 | +- **Maintainer: ** Jonathan D.A. Jewell < [email protected]> |
85 | 134 |
|
86 | 135 | --- |
87 | 136 |
|
88 | | -_This site is built with **casket-ssg** v1.0 (Haskell engine)_ |
| 137 | +Built with 🔮 by [Jonathan D.A. Jewell](https://github.com/hyperpolymath) | Licensed under [PMPL-1.0-or-later](https://github.com/hyperpolymath/palimpsest-license) |
0 commit comments