package soupault

  1. Overview
  2. Docs
Static website generator based on HTML rewriting

Install

Dune Dependency

Authors

Maintainers

Sources

3.0.0.tar.gz
md5=09fe1324d3d6f09741393c47f9f02e52
sha512=50b7d5aff7afbcfcdef0b390ac2df67daa4fdb86991065d6bf69b33a6ab344fc6743ea40b9d67c66933356226d9b24f6932b1c388b685a234996263024b9b705

Description

A website generator that works with page element tree rather than text and allows you to manipulate pages and retrieve metadata from existing HTML using arbitrary CSS selectors.

With soupault you can:

  • Generate ToC and footnotes.
  • Insert file content or an HTML snippet in any element.
  • Preprocess element content with external programs (e.g. run <pre> tags through a highlighter)
  • Extract page metadata (think microformats) and render it using a Jingoo template or an external script.
  • Export extracted metadata to JSON.

Soupault is extensible with Lua (2.5) plugins and provides an API for element tree manipulation, similar to web browsers.

The website generator mode is optional, you can use it as post-processor for existing sites.

Published: 17 Jul 2021

README

soupault

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.

It builds on the idea that HTML is a machine-readable format.

Client-side JavaScript has always been used to manipulate pages in-browser. For manipulating pages on disk, people traditionally used template processors. Soupault can parse an HTML page into an element tree, manipulate elements, and save the result to disk.

Web scrapers have been used for extracting data from someone else's pages. Microformats have been used to let other people know what to extract. For their own pages, people usually used "front matter". Soupault allows you to define your own "microformats" on the fly. For example, automatically use the first <h1>, or <h1 id="title"> for the page <title>. You can define your own fields based on CSS selectors and export the index to JSON, then make a HTML page with a blog archive or an RSS/Atom/JSONFeed from it.

Static site generators have been either easily extensible but written in interpreted languages or shipped as static binaries but self-contained. Soupault is an easy to install static binary, but it embeds a Lua interpreter that has access to the page element tree. Much like the DOM API for JS, but for Lua.

It's also friendly to existing websites. Clean URLs are optional. Assembling pages from a template and a body is also optional: if you page has an <html> element, it's excluded from the assembly stage. You can disable "templating", or mix unique and templated pages.

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

Visit https://www.soupault.app for details.

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

Installation

Pre-built binaries are available for Linux, Windows, and mac OS. You can download them from https://files.baturin.org/software/soupault and from Github releases (https://github.com/dmbaturin/soupault/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+https://github.com/dmbaturin/soupault

Contributing

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.

Dependencies (18)

  1. lua-ml >= "0.9.2"
  2. tsort >= "2.0.0"
  3. jingoo >= "1.4.2"
  4. base64 >= "3.0.0"
  5. spelll >= "0.3"
  6. odate
  7. containers >= "3.4"
  8. yaml >= "2.0.0"
  9. ezjsonm
  10. re >= "1.7.2"
  11. fmt
  12. logs
  13. fileutils
  14. otoml < "0.9.2"
  15. markup >= "1.0.0-1"
  16. lambdasoup >= "0.7.2"
  17. dune >= "2.0.0"
  18. ocaml >= "4.08"

Dev Dependencies

None

Used by

None

Conflicts (1)

  1. result < "1.5"