Soupault

Soupault is an open-source static site generator and HTML manipulation tool that works directly on the HTML element tree of each page instead of relying on Markdown files or front matter. It is written in OCaml, uses the lambdasoup library, and is maintained by the Pataphysical Society.

What is Soupault?

Soupault is an HTML manipulation tool and static site generator that operates on the HTML element tree of a page, taking HTML as input and producing modified HTML as output. It can inject new HTML into existing complete pages, create tables of contents from heading IDs, and extract metadata using CSS3 selectors defined in a TOML configuration file. The project is named after Philippe Soupault, a French dadaist writer, because it uses the lambdasoup library to parse and manipulate HTML.

Key Features

• Element-tree processing — Works with the HTML element tree rather than template files, enabling tasks like injecting HTML into existing pages without client-side JavaScript.
• No front matter — Metadata is extracted from HTML elements using CSS3 selectors, so hand-written static pages can be indexed without adding YAML or TOML headers.
• User-defined content model — Configure fields (title, excerpt, date, etc.) with selectors, required flags, attribute extraction, and fallback to content in a TOML config.
• Index view rendering — Define an index template and inject the rendered list of pages into any element matching a CSS selector, such as a blog index.
• Lua plugin support — Load Lua plugins to extend or reimplement built-in features.
• Page preprocessors and asset processors — Bring your own Markdown-to-HTML converters, Sass/Less compilers, image optimizers, or pipe HTML elements through external programs.
• Page processing hooks — Customize the processing workflow with hooks at defined stages.
• Dependency-free static binaries — Prebuilt for Linux (x86-64 and Aarch64), Windows, and macOS (x86-64), making installation and rollback straightforward.

Who is it for?

• Static site authors who want full control over their content model and page structure, without being forced into a specific templating language.
• Owners of existing hand-written HTML sites who want to add generated features like indexes, navigation, or tables of contents without adopting a traditional SSG.
• Toolchain tinkerers who want to extend a generator with Lua plugins, external programs, and custom preprocessors.

What can you do with Soupault?

• Bloggers: define a content model for titles, excerpts, and dates, then inject a rendered blog index into a page element.
• Website owners: inject shared HTML (e.g., headers, footers, ads) into all pages of an existing site.
• Documentation maintainers: auto-generate a table of contents that uses the IDs of HTML headings.
• Developers: pipe HTML elements through external programs, such as syntax highlighters, and integrate custom preprocessors for Markdown or other formats.

How does Soupault work?

Soupault is configured with a TOML file that defines the content model, processing rules, and index views. It processes every page in the site directory, evaluates CSS selectors to extract metadata, applies widgets and plugins, and writes the transformed HTML to an output directory.

FAQ

Is Soupault free?

Yes, Soupault is open source and free to use. Prebuilt binaries are available for Linux, Windows, and macOS, and the source can be installed through the OPAM package manager.

What does Soupault do?

Soupault is an HTML manipulation tool and static site generator that works on the HTML element tree. It extracts metadata using CSS selectors, injects new HTML, builds tables of contents, and applies processing rules defined in a TOML configuration.

How do I install Soupault?

Download prebuilt statically-linked binaries for Linux (x86-64 and Aarch64), Windows, and macOS (x86-64) from files.baturin.org or GitHub releases. Alternatively, run opam install soupault after installing OCaml.

Does Soupault use front matter?

No. Soupault extracts metadata directly from HTML elements using CSS3 selectors, so hand-written HTML pages can be indexed without front matter blocks.

Can Soupault run external programs?

Yes, Soupault can pipe HTML elements through external programs via its preprocess-element widget, and it supports custom page preprocessors and asset processors such as Sass compilers or image optimizers.