Static website generator based on HTML rewriting.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Daniil Baturin a685a899c9 3.1.0 release 1 month ago
.github/workflows Try migrating the CI to GitHub Actions. 7 months ago
examples Improve the example plugin a bit. 1 year ago
sample-site HTML entities & tags 4 months ago
src 3.1.0 release 1 month ago
.gitignore Initial commit 2 years ago
LICENSE Initial commit 2 years ago Reword the README and add an indexing showcase. 2 months ago
dune First prototype. 2 years ago
dune-project Update the version for new dependencies. 2 years ago
soupault.opam 3.1.0 release 1 month ago


Build Lines of code GitHub all releases

Soupault is an HTML manipulation tool. It can be any of:

  • static site generator
  • HTML processor
  • metadata extractor

or all of them at the same time.

Soupault works with the HTML element tree of the page, so it can do many thing that traditionally could be done with client-side JS: inject new HTML into existing complete pages, create a table of contents that preserves the id elements of HTML headings and more.

It also doesn't use front matter and extracts metadata from HTML instead, using a CSS3 selector to metadata field mapping, so even hand-written static pages can be indexed rather than treated as assets. For example:

  # Try to find <h1 id="post-title"> if it exists,
  # else use the first <h1> 
  selector = ["h1#post-title", "h1"]

  selector = ["p#post-excerpt", "p"]

  selector = ["time#post-date", "time"]
  extract_attribute = "datetime"
  fallback_to_content = true

Extracted metadata can then be rendered and injected into pages:

  # Insert rendered data into the element that matches "#blog-index" CSS selector.
  index_selector = "#blog-index"
  index_item_template = """
    <h2><a href="{{url}}">{{title}}</a></h2>
    <p><strong>Last update:</strong> {{date}}.</p>
    <a href="{{url}}">Read more</a>

Soupault is...

  • Eternal: it comes as a statically-linked binary with no dependencies.
  • Extensible: you can bring your own page preprocessors (e.g. Markdown to HTML convertors), pipe HTML elements through external programs, and load Lua plugins.
  • Flexible: most options are configurable and most built-in features can be reimplemented as Lua plugins.

Soupault is named after the French dadaist and surrealist writer Philippe Soupault because it's based on the lambdasoup library.

Visit for details.

For support and discussion, write a message to the mailing list.


Pre-built binaries are available for Linux, Windows, and mac OS. You can download them from and from Github releases (

You can verify release archive integrity using this signify/minisign key: RWRfW+gkhk/+iA7dOUtTio6G6KeJCiAEp4Zfozw7eqv2shN90+5z20Cy.

You can also install stable release versions from OPAM:

opam install soupault

Finally, you can build the latest development version with:

opam pin add git+


Bug reports and patches are always welcome. Feature requests and new features are also welcome, but please consider discussing them with the maintainer first.

You can submit patches either as Github pull requests or send them to the Sourcehut mailing list.