soupault
Soupault (soup-oh) is a static website generator/framework that works with HTML element trees<br>and can automatically manipulate them. It can be described as a robotic webmaster<br>that can edit HTML pages according to your rules, but doesn’t get tired of editing them.
You can use soupault for making blogs and other types of websites, pretty much like any other SSGs<br>(Jekyll, Hugo, Eleventy, etc.). However, you can also use it as a post-processor<br>for existing websites — a use case other tools don’t support.
Soupault is highly-configurable, extensible, and designed to give you complete control<br>over your website generation process.
If you are already familiar with other static site generators, check out the<br>comparison with Hugo, Zola, and Jekyll.<br>You may also want to read the FAQ.
Quick start
Soupault is very simple to install: if you are on Linux (x86-64), macOS, or Microsoft Windows,<br>you can just download an executable.
If you are starting a blog or an online book, you can grab a ready-to-use blueprint.
If you want to make a custom setup, read a guide to get a feel of soupault’s workflow:
Create a blog setup from scratch.
Use soupault as a post-processor for an existing website.
Why soupault?
Soupault is not like other static site generators — it works on the HTML element tree level.<br>Most SSGs treat HTML as an opaque format that can be generated with templates but cannot be read or manipulated.
Soupault treats HTML as a first-class format and that enables many use cases and features that are impossible for other SSGs.
Store pages in any format
Soupault works with HTML element trees, so you can store your pages in any format<br>that can be converted to HTML — all features will work the same no matter what the source format was.
There’s built-in Markdown support, but you can also configure HTML conversion commands for different file extensions<br>and soupault will call them automatically when it loads your pages.
Whatever formats and tools you want to use, you can easily do it. Want to use cmark for Markdown,<br>pandoc for reStructuredText, and Asciidoctor for AsciiDoc? That’s simple:
[preprocessors]<br>md = `cmark --unsafe --smart`<br>rst = `pandoc -f rst -t html`<br>adoc = `asciidoctor --embedded -o -`
Or you can write HTML pages by hand if you prefer.
Bring any external tools to your workflow and remove unnecessary client-side JavaScript
A lot of time people add non-interactive client-side JavaScript to compensate for missing features<br>in their SSGs. Soupault helps you keep your pages lighter by pre-rendering HTML with external<br>tools at build time instead.
In the simplest case, you can include the output of an external program in your page,<br>in any location identifiable with a CSS selector.
[widgets.page-generation-date]<br>widget = "exec"<br>command = "date -R"<br>selector = "datetime#generated-on"
But you can also pipe element content through an external program and insert the output back.<br>Run code examples through your favorite syntax highlighter, automatically check if they compile — there are many possibilities.
This is how this website highlights source code in and tags<br>with Andre Simon’s highlight:
# Runs the content of elements through a syntax highlighter<br>[widgets.highlight]<br>widget = "preprocess_element"<br>selector = '*[class^="language-"]'<br>command = 'highlight -O html -f --syntax=$(echo $ATTR_CLASS | sed -e "s/language-//")'
With additional scripts you can do much more, for example, render math with KaTeX at build time.
Extract page metadata from HTML, no front matter needed
Most static site generators make you write metadata in the "front matter", but soupault allows you to extract<br>it right from HTML instead.
You can define a mapping of CSS selectors to metadata fields. This is how you can add a list of all pages to your<br>main page, using the first heading tag (either , , or , whichever is present) of the page as its title:
[index]<br>index = true
[index.fields]<br>title = { selector = ["h1", "h2", "h3"] }
[index.views.page-list]<br>page = "index.html"<br>index_selector = "main"
index_template = '''<br>h2>All pagesh2><br>="page-list"><br>{% for e in entries %}<br>="{{e.url}}">{{e.title}}a>li><br>{% endfor %}<br>'''
Take advantage of HTML as a first-class format
Soupault’s DOM manipulation is as powerful as client-side JavaScript (without interactivity, of course),<br>but the result is a static page.
With built-in features, you can automatically create two-way footnotes,<br>use a highly-configurable ToC, or add a URL prefix to every link.<br>Most importantly, those features are available regardless of the original page format: whether the HTML was hand-written<br>or produced by a converter, they will work the same.
With Lua plugins you can do much more than that. You can transform existing HTML,<br>or create a DSL from "fake" elements and convert them to real HTML,<br>e.g. create a hyperlinked glossary.
The plugin API offers many possibilities, from adding and deleting HTML elements<br>to executing external programs, loading data from...