Soupault (soup-oh) is a static website generator and HTML processor.
Its distinctive feature is that it works with your page HTML element tree rather than text, so it can manipulate pages in ways many other tools can't.
- You don't need to change anything in the website to start using it
- All control flow is defined in a configuration file. The “template” (which is optional anyway) is just a page with some elements left empty.
- It can automatically manipulate pages regardless of their layout
-
Targets for HTML manipulation rules are specified with CSS selectors. This is how you can include a file into
<div id="header">:[widgets.insert-header] widget = "include" selector = "div#header" file = "includes/header.html"
this rule will work for every page that has a<div id="header">, no matter where exactly is it in the page. - It can extract metadata from pages
- There is no “front matter”. Instead, you tell soupault what to extract using CSS selectors again.
This makes soupault equally suitable for uniform Web 2.0 style websites and free-form Web 1.0 websites with lots of unique pages. You can also use it to enhance an existing website, whether it's handwritten or generated by another tool.
These are some of the things it can do for you:
- Assemble a complete website from a template (an empty page) and a directory with page body files.
- Insert files, HTML snippets, or output of external programs into your pages.
- Create a table of contents from the page headings.
- Create footnotes.
- Automatically call convertors from other formats (Markdown etc.) to HTML.
- Delete unwanted elements.
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 generatedsoupault.conffile, it's pretty detailed and well-commented.
You can also browse the source of this website and play with it.
Static website generator
As a static site generator, it can help you build a complete website from a template (an empty page) and a directory with page body files.
Its output is a completely static website in every possible sense: it needs no database etc. on the server side, and it also needs no client-side JavaScript (unless you add your own JavaScript of course). This ensures your site is fast, secure, accessible, and can be hosted anywhere for free or at a low cost.
You can easily change the site design by editing the template and rebuilding the site. It's also easy to move reusable bits to separate files (like headers, footers, navigation menus and so on) and include them in every page.
Unlike other generators, soupault doesn't limit you to all pages looking the same. You can add pages with unique layouts, and still have them processed, rather than treated as static assets. You can also opt out from templating completely and use soupault as a postprocessor for an existing website.
HTML processor
Soupault can also work as an HTML processor for existing pages, whether they are handwritten or generated by another tool. You can enhance your site with tables of contents, inject a viewport meta tag, or do something else to every page, even if they are all unique.
All features are available in both website generator and HTML processor modes, so you don't have to edit any pages to start automating tedious tasks.
Soupault decides whether to work like a website generator or an HTML processor
by checking if a page file has an <html> element in it. If it does not,
then it first assembles a complete page from that file and the template. If it does, then it knows
the page is already complete and only applies HTML transormation actions, like generating a table of contents.
This way you can mix templated and unique pages easily.
How it's different from other tools?
Based on HTML rewriting
Website generators like Jekyll or Hugo generate HTML by filling the blanks in a template. Soupault parses HTML and then transforms and enhances it. It's conceptually similar to DOM manipulation with client-side JavaScript, only it produces static pages that will work even with JS disabled.
The “template” is really just an HTML page with some elements left empty.
Instead of inserting template tags like {{content}} in your page, you tell soupault how to find target elements using CSS selectors, like body, .footnote, or div#content.
So, if you have ever written a CSS stylesheet or worked with functions like $() from jQuery or Document.querySelector() from vanilla JS,
you already know the syntax.
It allows you to do things that are impossible with tools based on template processors.
For example, this config snippet will insert a table of contents before the first <h1> element of the page:
[widgets.insert-toc] widget = "toc" selector = "h1" min_level = 2 action = "insert_before"
No forced Markdown
The only format soupault uses internally is HTML. However, you can configure it to automatically convert your files to HTML before further processing.
Whether you are a fan of a particular Markdown flavor, reStructuredText, or anything else, you can use it if you install a convertor. You can also use multiple formats and convertors at once.
Native and fast, but extensible
Many generators are extensible with plugins but require a Ruby/Python/JS interpreter and runtime. Hugo is a static executable that is fast and trivial to install, but it's not extensible.1 With soupault you can have both.
It's available as a native, standalone executable (~6MB) for Linux, Windows, and macOS that can be installed just by copying, and isn't going to stop working in newer operating system versions.
Soupault is quite fast and can build a moderate size website in under a second.
It's also extensible with Lua plugins.2 Plugins have full access to the element tree of the page, much like JavaScript, but without a browser.No external metadata needed
Classic website generators store page metadata in a “front matter”—a machine-readable header placed before the page content.
Soupault doesn't need it because it can extract metadata from the HTML itself, again using CSS selectors. For example, you can create a simple blog feed
from existing pages using the <h1> element for the post title and the first <p> for the excerpt.
See this post for a simple blog recipe.
You can also define custom fields and export the entire site index to JSON for processing by external scripts.
Want to see it in action?
Here's a screencast of basic usage:
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)3
- soupault-1.8.0-linux-x86_64.tar.gz
- Microsoft Windows (7 and newer, 32-bit)
- soupault-1.8.0-win32.zip
- macOS
- soupault-1.8.0-macos.tar.gz
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.4
Graphics
The 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.
