diff --git a/README.adoc b/README.adoc index 6b5fe4e..fab1d0f 100644 --- a/README.adoc +++ b/README.adoc @@ -6,177 +6,147 @@ :source-highlighter: highlight.js image:https://img.shields.io/badge/license-MIT%20OR%20AGPL--3.0-blue[License] -image:https://img.shields.io/badge/RSR-compliant-gold[RSR Compliant] -image:https://img.shields.io/badge/MCP-adapters-green[MCP Adapters] -Satellite SSG implementation providing Deno/JavaScript MCP adapters for 28 static site generators. +Static site generator in Ada. -toc::[] - -== Overview +____ +Let contracts bind. Let ranges guard. Let pages render. +____ -**noteg-ssg** is a satellite project in the https://github.com/hyperpolymath[hyperpolymath] ecosystem that provides Model Context Protocol (MCP) adapters for 28 different static site generators across multiple programming languages. +toc::[] -This project integrates with the https://github.com/hyperpolymath/poly-ssg-mcp[poly-ssg-mcp] hub to provide a unified interface for working with various SSGs. +== Who Is This For? -=== Key Features +* **Safety-conscious engineers** who value compiler-proven correctness +* **Ada enthusiasts** seeking modern web tooling in their language of choice +* **Systems programmers** who want strong typing for their content pipelines +* **Documentation teams** requiring mission-critical reliability -* **28 SSG Adapters** - Support for SSGs written in Rust, Haskell, Elixir, Julia, Scala, and more -* **MCP Protocol** - Standardised Model Context Protocol interface -* **Deno Runtime** - All adapters run on Deno for consistent cross-platform execution -* **RSR Compliant** - Follows Rhodium Standard Repository guidelines +== Why noteg-ssg? -== Supported Static Site Generators +Ada brings unique strengths to static site generation: -[cols="1,1,2"] -|=== -|Adapter |Language |Description - -|babashka |Clojure |Babashka-based SSG -|cobalt |Rust |Static site generator in Rust -|coleslaw |Common Lisp |Lisp-based SSG -|cryogen |Clojure |Static site generator for Clojure -|documenter |Julia |Julia documentation generator -|ema |Haskell |Haskell static site generator -|fornax |F# |F# static site generator -|franklin |Julia |Julia-based SSG with live editing -|frog |Racket |Racket static blog generator -|hakyll |Haskell |Hakyll static site generator -|laika |Scala |Scala documentation tool -|marmot |Crystal |Crystal-based SSG -|mdbook |Rust |Rust book/documentation generator -|nimble-publisher |Elixir |Nimble-based Elixir publisher -|nimrod |Nim |Nim static site generator -|orchid |Kotlin |Kotlin documentation generator -|perun |Clojure |Clojure static site generator -|pollen |Racket |Racket publishing system -|publish |Swift |Swift static site generator -|reggae |D |D language SSG -|scalatex |Scala |Scala text processor -|serum |Elixir |Simple static site generator for Elixir -|staticwebpages |Julia |Julia static web pages -|tableau |Elixir |Elixir static site generator -|wub |Tcl |Tcl web framework -|yocaml |OCaml |OCaml static site generator -|zola |Rust |Fast static site generator in Rust -|zotonic |Erlang |Erlang CMS and framework +[cols="1,2"] |=== +|Feature |Benefit -== Installation +|**Strong Static Typing** +|Content schemas enforced at compile time -=== Prerequisites +|**Contract-Based Design** +|Pre/post conditions guard your build pipeline -* https://deno.land/[Deno] runtime (v1.40+) -* The specific SSG you want to use must be installed on your system +|**Range Types** +|Invalid states become unrepresentable -=== Setup +|**Tasking Model** +|Parallel rendering with formal concurrency guarantees -[source,bash] ----- -# Clone the repository -git clone https://github.com/hyperpolymath/noteg-ssg.git -cd noteg-ssg ----- +|**SPARK Subset** +|Provably correct transformations where needed +|=== -== Usage +No null. No buffer overflows. No silent failures. The compiler proves it. -Each adapter provides a standard MCP interface with common tools: +== Quick Start -[source,javascript] +[source,ada] ---- -// Example: Using the Zola adapter -import { connect, tools } from './adapters/zola.js'; - -// Connect to verify Zola is installed -await connect(); - -// Use available tools -const result = await tools.find(t => t.name === 'init').execute({ name: 'my-site' }); +with Noteg.Site; +with Noteg.Markdown; + +procedure Build is + Site : Noteg.Site.Instance := Noteg.Site.Create + (Source => "content/", + Output => "_site/"); +begin + Site.Add_Processor (Noteg.Markdown.Processor); + Site.Build; +end Build; ---- -=== Common Tools - -All adapters typically provide these tools: - -* `init` - Initialize a new site -* `build` - Build the static site -* `serve` - Start a development server -* `check` - Validate site configuration -* `version` - Get the SSG version - == Architecture [source] ---- -noteg-ssg (satellite) - | - +-- adapters/ # 28 MCP adapter implementations - | +-- zola.js - | +-- hakyll.js - | +-- ... - | - +-- Integrates with: poly-ssg-mcp (hub) + ┌─────────────┐ + │ Watcher │ (filesystem events) + └──────┬──────┘ + │ + ┌──────▼──────┐ + │ Parser │ (content → AST) + └──────┬──────┘ + │ + ┌────────────┼────────────┐ + │ │ │ + ┌──────▼──────┐ ┌───▼───┐ ┌──────▼──────┐ + │ Markdown │ │ AsciiDoc │ │ Template │ + └──────┬──────┘ └───┬───┘ └──────┬──────┘ + │ │ │ + └────────────┼────────────┘ + │ + ┌──────▼──────┐ + │ Renderer │ (AST → HTML) + └──────┬──────┘ + │ + ┌──────▼──────┐ + │ FileEmitter │ (write output) + └─────────────┘ ---- -=== Ecosystem Position +Each stage operates under Ada's contract model—preconditions validate input, postconditions guarantee output. -* **This project**: Satellite SSG adapter implementations -* **poly-ssg-mcp**: Central hub providing unified MCP server -* **rhodium-standard-repositories**: RSR compliance standard +== Features -== Development +* **Markdown & AsciiDoc** - First-class support for technical documentation +* **Template Engine** - Type-safe templating with compile-time validation +* **Incremental Builds** - Only rebuild what changed +* **Live Reload** - Development server with instant feedback +* **Asset Pipeline** - CSS/JS processing with integrity verification -=== Prerequisites +== Ada Primer -* Deno runtime -* (Optional) https://github.com/casey/just[just] task runner -* (Optional) Nix for reproducible environments +For those new to Ada's safety model: -=== Running Tests +[cols="1,2"] +|=== +|Concept |Purpose -[source,bash] ----- -# Run all adapter tests -deno test adapters/ +|`subtype Positive is Integer range 1 .. Integer'Last` +|Range types eliminate invalid values -# Test a specific adapter -deno test adapters/zola.js ----- +|`Pre => Source /= null` +|Preconditions enforce caller obligations -=== Adding New Adapters +|`Post => Result.Is_Valid` +|Postconditions guarantee results -1. Create a new file in `adapters/` following the existing pattern -2. Export: `name`, `language`, `description` -3. Implement: `connect()`, `disconnect()`, `isConnected()`, `tools[]` -4. Add tests +|`pragma SPARK_Mode` +|Enable formal verification subset +|=== -See link:CONTRIBUTING.md[CONTRIBUTING.md] for full guidelines. +== Ecosystem -== Security +noteg-ssg integrates with the https://github.com/hyperpolymath/poly-ssg-mcp[poly-ssg-mcp] hub via MCP adapters written in ReScript. -Please report security vulnerabilities through GitHub Security Advisories: -https://github.com/hyperpolymath/noteg-ssg/security/advisories/new +Related projects: -See link:SECURITY.md[SECURITY.md] for our full security policy. +* https://github.com/hyperpolymath/poly-ssg-mcp[poly-ssg-mcp] - Unified MCP server for static site generators +* https://github.com/hyperpolymath/poly-container-mcp[poly-container-mcp] - Container orchestration adapters +* https://github.com/hyperpolymath/poly-iac-mcp[poly-iac-mcp] - Infrastructure as code adapters -== License +== Requirements -This project is dual-licensed under: +* GNAT (GNU Ada compiler) or other Ada 2012+ compiler +* Deno (for MCP adapter integration) -* MIT License -* AGPL-3.0-or-later +== License -See link:LICENSE.txt[LICENSE.txt] for details. +Dual-licensed under MIT and AGPL-3.0-or-later. See link:LICENSE.txt[LICENSE.txt]. == Contributing -Contributions are welcome! Please read our link:CONTRIBUTING.md[Contributing Guidelines] and link:CODE_OF_CONDUCT.md[Code of Conduct] before submitting. - -== Links - -* https://github.com/hyperpolymath/noteg-ssg[GitHub Repository] -* https://github.com/hyperpolymath/poly-ssg-mcp[poly-ssg-mcp Hub] -* https://github.com/hyperpolymath[hyperpolymath Organization] +See link:CONTRIBUTING.md[CONTRIBUTING.md] for guidelines. ---