Can soupault be used as a post-processor for an existing website?

Updated

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

Situation Soupault as post-processor
You have existing HTML you don't want to regenerate Fits — it edits pages in place according to rules
You want to keep your current source format or toolchain Fits — it can call external converters (e.g. cmark, pandoc, Asciidoctor) via preprocessors
You want a batteries-included theme with no configuration Poor fit — soupault is highly configurable and expects you to define behavior
You only need one-time edits Probably overkill — a script may be simpler

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.