How to Get Started with soupault

Updated

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:

Path Use it when What you get
Ready-to-use blueprint You want a blog or an online book and don't want to design the setup A working project you can edit
Create a blog setup from scratch You want a custom site and need to understand the workflow A guide that walks through soupault's model
Post-processor for an existing website You already have an HTML site and want to manipulate it A guide for running soupault over existing pages

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.