Skip to content

Add language support for Eclipse SSG #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
hyperpolymath merged 1 commit into from
Dec 26, 2025
Merged

Add language support for Eclipse SSG #3

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
220 changes: 95 additions & 125 deletions README.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

---

Expand Down
Loading