Soupault (soup-oh) is an HTML manipulation tool.

You can use it as a...

It's best described as a robotic webmaster. Like a human webmaster, it understands HTML, but doesn't get tired of editing it. It can insert files, HTML snippets, and output of external programs in your pages, generate tables of contents and footnotes, and more. It can also delete elements from pages.

Suppose you want to add stylesheet link to the <head> of every page, before all other elements. You can tell soupault to do exactly that:

[widgets.css-reset]
  widget = 'insert_html'
  html = '<link rel="stylesheet" href="/styles/reset.css" type="text/css">'
  selector = 'head'
  action = 'prepend_child'

Friendly to existing sites and unique pages

One of the goals of soupault is to make working with freeform Web 1.0 and uniform Web 2.0 style websites equally easy.

Classic website generators like Jekyll or Hugo assume all pages are built from a template, and pages with unique layout can only be included as static assets. Soupault works with the element tree of the page rather than text, so it can automatically manipulate pages regardless of their exact layout—you write manipulation rules using CSS selectors.

It can detect whether a file is a complete page or a page body that needs to be inserted in a template (by checking if it has a <html> element in it).

The page template is just an HTML file with some elements left empty—you tell soupault where to insert the content by giving it a CSS selector (by defaults it inserts the content at the end of the page <body>).

You can choose whether to produce “clean URLs” or preserve the file names and extensions exactly.

It can also extract page metadata using CSS selectors. You can make a simple list of pages in a directory using their first heading tag as a title, or make a blog feed with arbitrary fields and layout. You can also export the metadata to a JSON file and generate Atom feeds or custom archive pages from it.

Not opinionated

Soupault doesn't impose any particular workflow on you. You can either have it assemble pages from the template and content files, or just post-process your handwritten pages.

You can write all pages in plain HTML, or configure convertors and use any formats like Markdown, reStructuredText, TeX, or any other.

You can also schedule the execution of HTML processing steps, for example, first include a navigation menu in the page, then run a plugin that highlights the link to the current page.

Easy to install and future-proof

For Linux, Windows, and mac OS, soupault is available as a standalone executable with no dependencies. You can install it simply by copying the file. It will also keep working for years to come, even if development of new versions ceases.

The fact that it's compiled to machine code rather than interpreted also makes it faster than many alternatives.

Extensible

Standalone doesn't mean self-contained. Soupault is extensible in two ways.

The first way to extend it is Lua plugins. They have full access to the page element tree, similar to the DOM API in JavaScript, so they can manipulate pages in arbitrary ways.

The other way is to pipe element content through an external program. For example, you can run source code snippets from <pre class="language-*"> elements through a syntax highlighter and replace the original content of the element with its output.

Ready to start?

Read a step by step tutorial to see what it's like.

You can also browse the source of this website and play with it, or check out websites of other soupault users.

Download and install

The simplest way to start using soupault is to download a prebuilt executable. Just unpack the archive and you are ready to go.

Downloads:

Linux (x86-64)1
soupault-1.12.0-linux-x86_64.tar.gz (sig)
Microsoft Windows (7 and newer, 32-bit)
soupault-1.12.0-win32.zip (sig)
macOS
soupault-1.12.0-macos.tar.gz (sig)

You can verify digital signature using this public key: RWRfW+gkhk/+iA7dOUtTio6G6KeJCiAEp4Zfozw7eqv2shN90+5z20Cy

Soupault uses minisign for release signing. To learn about its advantages over GPG, read signify: Securing OpenBSD From Us To You. One obvious advantage is that you don't need to import the key anywhere, you can pass it as a command line argument:

minisign -Vm soupault-1.12.0-win32.zip -P RWRfW+gkhk/+iA7dOUtTio6G6KeJCiAEp4Zfozw7eqv2shN90+5z20Cy

Soupault is free software published under the MIT license. You can build it from source for any platform supported by the OCaml programming language and contribute to it. The source code is available from github.com/dmbaturin/soupault.

If you already have OCaml and opam installed, you can also install from the opam repository: opam install soupault.

How to use it?

The HOWTO should be a good start. Then read the reference manual for details. There's also a blog with tips and tricks.

Why it's named soupault?

Soupault is named after the French dadaist and surrealist writer Philippe Soupault because it's based on the lambdasoup library. Its development is sponsored by the College of 'Pataphysics.2

Graphics

Soupault logo is a stick horse. It's a reference to the meeting where Philippe Soupault et al. chose a name for their movement by opening a dictionary at a random word and landed on “dada (n.), a colloquial for a stick horse”, which is why they named it “dadaism”.

If you are using soupault for your site or want to raise awareness of it, feel free to put a button there.

Who's behind it?

So far just me, Daniil Baturin, but everyone is welcome to send a patch/pull request or a suggestion. It has grown out of the bunch of ad hoc scripts that used to power my own website, and then I thought I can as well make it usable for everyone who finds other generators too annoying or too limiting.

Feel free to contact me.

1Before you have a chance to interject for a moment, I'll say that it's compiled statically with musl, so it will work on any Linux-based OS, not just GNU/Linux.

2Not really.