Soupault (soup-oh) is an HTML manipulation tool.
You can use it as a...
- Static website generator
- HTML processor
- Metadata extractor
- Any combination of the above
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.
For example, suppose you want to add a link to a stylesheet 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 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
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.
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.
Standalone doesn't mean self-contained. Soupault is extensible in two ways.
The other way is to pipe element content through an external program. For example, you can run source code snippets
<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.
- If you already have a website: how to use soupault as an HTML processor.
If you are starting a new site: run
soupault --initin an empty directory and read the generated
soupault.conffile, it's pretty detailed and well-commented.
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.
- Linux (x86-64)1
- Microsoft Windows (7 and newer, 32-bit)
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?
Why it's named soupault?
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.