Repository files navigation

Soupault is an HTML manipulation tool. It can be a static site generatoror an HTML (post-)processor for existing websites and allows you to define your own content modeland page processing rules using built-in actions, external executables, templates, or Lua plugins.

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

It also doesn't use front matter but extracts metadata from HTML instead: you tell it what to extract using CSS3 selectors,so even hand-written static pages can be indexed rather than treated as opaque assets.

For example, here's what a content model for a blog may look like:

# Post title[index.fields.title]# Try to find <h1>,# else use the first <h1>selector = ["h1#post-title","h1"]# Fail the build if post title cannot be foundrequired =true# Post excerpt[index.fields.excerpt]# Use <p> if a page has it,# else use the first paragraph.# This allows using a paragraph other than the first one# as the post excerpt.selector = ["p#post-excerpt","p"]# Post date[index.fields.date]selector = ["time#post-date","time"]# Extract the datetime="" attribute from the <time> element,# if it's set.extract_attribute ="datetime"# If there's no datetime attribute in <time>,# then use that element's contentfallback_to_content =true

Extracted metadata can then be rendered and injected into pages:

[index.views.blog]# 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>    <p>{{excerpt}}</p>    <a href="{{url}}">Read more</a>"""

Soupault is...

• Durable and easy to upgrade or roll back: it's available as a statically-linked binary with no dependencies.
• Extensible: you can bring your ownpage preprocessors(e.g., Markdown to HTML convertors), defineasset processors(e.g., a Sass/Less compiler, an image optimizer),pipe HTML elements throughexternal programs,and loadLua plugins.
• Flexible: most options are configurable, most built-in features can be reimplemented as Lua plugins,and there arepage processing hooks.

Soupault is named afterPhilippe Soupault,a French dadaist and surrealist writer and poet,because it useslambdasoup library to work with tag soups.

Visitsoupault.app for details.

For support and discussion, write a message to themailing list.

Prebuilt binaries are available for Linux (x86-64 and Aarch64), Windows, and macOS (x86-64).You can download them fromhttps://files.baturin.org/software/soupaultand from GitHub releases (https://github.com/PataphysicalSociety/soupault/releases).

You can verify release archive integrity using this minisign key:

minisign -VP RWRfW+gkhk/+iA7dOUtTio6G6KeJCiAEp4Zfozw7eqv2shN90+5z20Cy -m <file>

You can also install stable release versions fromOPAM:

opam install soupault

Finally, you can build the latest development version with:

opam pin add git+https://github.com/PataphysicalSociety/soupault

To build static binaries, you need to install OCaml with musl runtime,then use thestatic Dune profile:

# For OCaml 4.14.2, adjust for your desired versionopam switch create 4.14.2-musl ocaml-variants.4.14.2+options ocaml-option-musl ocaml-option-staticopam switch 4.14.2-musl# Build static binariesdune build --profile=static

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 contribute either throughGitHubor throughCodeberg.