soupault.net

Install soupault by downloading a single executable for Linux (x86-64), macOS, or Windows, then either grab a ready-made blueprint for a blog or online book, or follow the from-scratch guide if you want a custom setup. The post-processor route is the one path other static site generators don't offer: you can point soupault at an existing HTML site and have it edit pages according to your rules.

Install soupault

soupault ships as a standalone executable, so there is no package manager or runtime to set up first.

1. Download the executable for your platform: Linux (x86-64), macOS, or Microsoft Windows.
2. Make it runnable (on Linux/macOS, mark it executable) and put it somewhere on your PATH.
3. Run it against a project directory to confirm it starts.

The site does not document a package-manager install or a build-from-source requirement, so treat the executable download as the supported starting point.

Pick your starting path

There are three documented ways in, and they suit different situations:

If you have never used soupault, the from-scratch guide is the one that teaches the mental model. The blueprint is faster but assumes you'll accept its structure.

Understand the workflow before you configure anything

soupault works on the HTML element tree rather than treating HTML as an opaque output format. That single design choice explains most of what follows.

• Pages can be stored in any format that converts to HTML. Markdown support is built in. For other formats you configure conversion commands per file extension, and soupault calls them automatically when it loads pages.
• Conversion is configured, not hardcoded. For example, the documented configuration maps extensions to commands:

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

With that in place, a .md file goes through cmark, a .rst file through pandoc, and an .adoc file through Asciidoctor — and every soupault feature behaves the same regardless of which source format a page came from. You can also write HTML pages by hand.

• Because HTML is a first-class format, soupault can read and manipulate it. This is what makes the post-processor use case possible: instead of generating pages from templates, it can take pages that already exist and edit them by rule.

Try the post-processor path if you already have a site

This is the capability the site specifically calls out as unsupported by other tools. The practical sequence is:

1. Point soupault at your existing site directory.
2. Write rules describing the edits you want applied to the HTML element tree.
3. Run soupault and check the resulting pages.

The value here is removing repetitive manual HTML edits — the site describes soupault as a "robotic webmaster" that edits pages according to your rules without getting tired of it. It also notes that people often add non-interactive client-side JavaScript to compensate for missing SSG features; if that describes your current site, this is the path where soupault can replace some of that work.

Verify it worked

After either path, confirm three things:

• The pages you expect were produced or modified in the output location.
• Preprocessor conversions ran for each non-HTML source format you configured (a page that renders as raw text usually means the command for that extension is wrong or missing).
• Any rules you wrote actually matched elements — a rule that matches nothing fails silently in the sense that the page simply comes out unmodified.

Common sticking points

• Assuming a package install exists. The documented install is the downloadable executable; don't wait for a distro package.
• Forgetting the preprocessor mapping. A source format works only if you've declared a command for its extension. Adding .rst files without a rst entry means they won't be converted.
• Choosing the blueprint when you need to learn the model. Blueprints get you running fast, but the from-scratch guide is what explains how soupault's rules and element-tree manipulation fit together.
• Treating it like a template-only SSG. If you approach it expecting Jekyll/Hugo-style templating only, you'll miss the post-processing and HTML-manipulation features that are the reason to pick soupault.

For a direct feature-by-feature comparison, the site links a comparison with Hugo, Zola, and Jekyll, plus an FAQ — worth reading before committing if you're migrating from another generator.

Yes. Soupault is explicitly designed to work as a post-processor for existing websites, a use case the project says other static site generators don't support. Instead of only generating HTML from templates, it reads and manipulates HTML element trees, so it can take pages you already have and edit them according to your rules. The trade-off is that you need to define those rules in configuration rather than expect a ready-made theme to do the work.

Why post-processing is possible

Most static site generators treat HTML as an output format: templates go in, HTML comes out, and the generated HTML is not something the tool reads back or edits. Soupault treats HTML as a first-class format and operates on the element tree level. That means it can parse existing HTML, find elements, and modify them — which is what makes post-processing an existing site feasible at all.

The project describes itself as "a robotic webmaster that can edit HTML pages according to your rules, but doesn't get tired of editing them." The practical effect: repetitive edits you'd otherwise do by hand or with one-off scripts can be expressed as rules and applied consistently across a site.

What post-processing looks like in practice

The workflow is: point soupault at your existing HTML, define rules for what to change, and let it rewrite the pages. Because it works on element trees, the rules target HTML structure rather than raw text, so they survive unrelated markup changes better than find-and-replace.

Typical tasks this suits:

• Injecting or updating a shared header, footer, or navigation block across many pages
• Adding or modifying attributes, classes, or metadata on matching elements
• Removing or replacing elements that match a selector
• Applying the same transformation to a whole directory of already-written HTML

The project's own documentation lists "Use soupault as a post-processor for an existing website" as one of the two main getting-started paths, alongside building a blog from scratch.

Where it fits versus where it doesn't

The same element-tree approach also means you can store pages in any format that converts to HTML, since all features work the same regardless of source format. Built-in Markdown support exists, and you can configure conversion commands per file extension.

What to check before committing

• Rule-based, not template-based. You'll write configuration describing what to change, not fill in a theme. Budget time for that.
• It's a post-processor, not a migration tool. It edits HTML you already have; it doesn't restructure your content model for you.
• Reversibility. Since it rewrites pages, keep your originals under version control so you can compare and roll back.

If your goal is to apply consistent, repeatable HTML transformations to a site that already exists, soupault is built for exactly that. If you want a generator to produce a site from scratch with minimal setup, the project's blueprints for blogs and online books are the more direct starting point.

Soupault can work with any page format that can be converted to HTML, because it operates on the HTML element tree rather than on a specific source syntax. Markdown is supported out of the box, and you can configure conversion commands for other file extensions so soupault calls the right external tool automatically when it loads a page. The practical condition is that you have a converter that turns your source format into HTML — once that exists, soupault’s features apply the same way regardless of what you wrote the page in.

Why format flexibility is possible

Most static site generators treat HTML as an output-only format: templates generate it, but the generator itself doesn’t read or manipulate the resulting markup. Soupault instead treats HTML as a first-class format and works on the element tree. That design choice is what lets it accept pages from many source formats — by the time soupault processes a page, it is working with HTML elements, not with Markdown, reStructuredText, or AsciiDoc syntax.

This also means features behave consistently across formats. A table of contents, an include, or a rewrite rule does not need a separate implementation for each source language.

Built-in Markdown support

Markdown works without extra configuration. If you are starting a blog or an online book, soupault provides ready-to-use blueprints, so you don’t have to assemble a Markdown pipeline yourself.

Configuring converters for other formats

For anything beyond Markdown, you map a file extension to a conversion command. Soupault runs that command when it loads a page with that extension. The documented example uses a [preprocessors] section:

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

Read this as a pattern rather than a fixed list:

• The key (md, rst, adoc) is the file extension soupault should match.
• The value is the shell command that reads the source and writes HTML.
• Each command is invoked automatically on page load, so you don’t run converters by hand before building.

The same mechanism is what makes the “any format” claim concrete: if a tool can emit HTML, you can wire it in.

What this looks like in practice

Suppose you keep documentation in reStructuredText and notes in AsciiDoc, alongside Markdown blog posts. You add entries for rst and adoc to [preprocessors], point them at pandoc and asciidoctor, and leave md on the built-in path. When soupault loads each page, it converts the source to HTML first, then applies your site-wide rules — menus, includes, rewrites — uniformly. You don’t maintain separate logic per format, and you don’t need client-side JavaScript to compensate for a generator that can’t read your markup.

You can also write HTML pages by hand. Since HTML is the native format, hand-written pages need no conversion step at all.

Choosing a format

The deciding factor is usually what your content already is. Since all features work the same regardless of source format, there is little reason to convert existing material just to fit the generator.

Common sticking points

• The converter must output HTML to stdout in a form soupault can parse. Check the flags your tool needs for that; the example commands show tool-specific options such as --unsafe --smart, -t html, and -o -.
• Extension matching is what triggers conversion. A file whose extension has no entry and isn’t Markdown or HTML won’t be converted the way you expect.
• Conversion happens at load time. If a converter fails or isn’t installed, the page won’t reach the element-tree stage where soupault’s features apply.

If you want to see the workflow end to end, soupault’s own guides cover creating a blog setup from scratch and using it as a post-processor for an existing site.

Soupault's own site answers both questions directly: it has a section titled "Who's behind it?" and another titled "Why it's named soupault?" Those two sections are the place to look for the project's origin and naming story. The site also gives a pronunciation hint — soupault is said as "soup-oh" — which is the first clue to the name.

Where the answers live on the site

The homepage navigation includes both sections, so you don't need to dig through documentation or source code to find them:

• "Why it's named soupault?" — explains the origin of the name.
• "Who's behind it?" — identifies the people or person maintaining the project.

If you arrived at soupault.net from a search engine or a link to the quick start guide, scroll the page or use the section headings to jump to these two blocks.

What the name tells you before you read the section

The pronunciation note ("soup-oh") is worth keeping in mind. It signals that the name is not meant to be read as English "soup-ault" but as a French-style word — the spelling resembles the French surname Soupault. That is a useful hint for how the project presents itself, but the site's own "Why it's named soupault?" section is the authoritative explanation, so treat the pronunciation as a pointer rather than the full story.

Why the maintainer question matters for choosing a tool

Knowing who is behind a static site generator is a practical maintenance question, not just trivia. Soupault is described on its site as a static website generator/framework that works with HTML element trees and can automatically manipulate them — "a robotic webmaster that can edit HTML pages according to your rules." It is also positioned as usable both as a normal SSG (like Jekyll, Hugo, or Eleventy) and as a post-processor for existing websites, a use case the site says other tools don't support.

That combination — a post-processor mode plus a highly configurable, extensible design — means you are relying on the project's maintainers for a tool that may sit in the middle of an existing publishing pipeline. Checking "Who's behind it?" tells you whether the project has identifiable, active maintainers rather than being an abandoned experiment.

A quick way to verify project health

Beyond the two homepage sections, you can cross-check the maintainer information against the project's development activity:

1. Read "Who's behind it?" on soupault.net to see who is named.
2. Look for a link to the source repository or issue tracker from the site.
3. Check whether that repository shows recent commits or releases.

The site itself does not list pricing or login requirements in the material available, so don't assume anything about cost or accounts from the absence of such signals — check the site directly if that matters to you.

Bottom line

For the naming story and the maintainer identity, go straight to the "Why it's named soupault?" and "Who's behind it?" sections on soupault.net. The pronunciation "soup-oh" is your first hint about the name's origin, and the maintainer section is the right place to judge whether the project has people actively standing behind it.

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

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.