What Is Soupault and How Is It Different from Other Static Site Generators?

Updated

Soupault is a static website generator and framework that operates on HTML element trees rather than treating HTML as opaque template output. That single design decision is the source of nearly everything that distinguishes it from Jekyll, Hugo, Eleventy, and similar tools. If you want a conventional blog generator, soupault can do that job. If you want to programmatically rewrite the HTML of a site you already have — something most SSGs don't support at all — soupault is built for exactly that.

The core difference: HTML as a first-class format

Most static site generators treat HTML as something you produce: you write Markdown or templates, and the generator emits HTML that it never looks at again. Soupault instead parses pages into an HTML element tree and lets you manipulate that tree according to rules you define. The project describes itself as a "robotic webmaster" that edits HTML pages according to your rules without getting tired of it.

This matters because it unlocks use cases that are structurally impossible in template-only generators:

  • Post-processing existing sites. You can point soupault at HTML you already have and have it inject, move, or rewrite elements — no migration to a new template system required.
  • Consistent manipulation regardless of source format. Because everything is normalized to an element tree before your rules run, the same features work whether a page started as Markdown, reStructuredText, or hand-written HTML.
  • Removing client-side JavaScript. A common reason people add non-interactive JavaScript is to compensate for missing generator features. Tree-level manipulation lets you do that work at build time instead.

You can store pages in any format

Soupault has built-in Markdown support, but it also lets you configure conversion commands per file extension, which it calls automatically when loading pages. The documentation gives this example:

[preprocessors]
md = `cmark --unsafe --smart`
rst = `pandoc -f rst -t html`
adoc = `asciidoctor --embedded -o -`

With that configuration, .md files go through cmark, .rst through pandoc, and .adoc through Asciidoctor — and all of soupault's features apply identically afterward. You can also write HTML by hand if you prefer. The practical consequence: you aren't locked into one authoring format, and you can bring external tools into the workflow rather than waiting for the generator to support them natively.

Two ways to use it

Use case What it looks like Who it suits
Full site generator Start from a blueprint for a blog or online book, or build a custom setup from scratch People who want a normal SSG workflow but with tree-level control
Post-processor Run soupault over an existing website's HTML to apply rules People with a site already built by other means who need automated HTML manipulation

The second row is the one other tools generally don't cover. If your site already exists and you just need systematic edits applied across it, that's a supported first-class workflow rather than a hack.

Getting started

Installation is deliberately simple: on Linux (x86-64), macOS, or Windows you can download an executable. From there the documented paths are:

  • Ready-made blueprint — grab one if you're starting a blog or an online book.
  • Blog setup from scratch — a guide for a custom configuration.
  • Post-processor setup — a guide for applying soupault to an existing website.

If you already know other generators, the project also publishes a comparison with Hugo, Zola, and Jekyll, plus an FAQ, which are the fastest ways to map your existing mental model onto soupault's.

What to weigh before choosing it

Soupault is described as highly configurable, extensible, and designed to give you complete control over the generation process. That control is the selling point, and it's also the trade-off: a tool that exposes the HTML tree and lets you script arbitrary transformations asks more of you than one that hides HTML behind templates. If your needs are a standard blog with conventional theming, the extra power may go unused. If you have HTML you need to manipulate automatically — especially HTML you didn't generate — the tree-level model is the reason to pick soupault over the alternatives.