package soupault
Install
Dune Dependency
Authors
Maintainers
Sources
md5=e9d5c935fab5f5138e90433b8ef7a421
sha512=2370659a15dc511e4e81c82e946162abefe54f7838d324ba0dee0db7bf09ad82b5a5eb5ca6915875e9715ed953b43438b3185255ea3ec782c5e753515a3e462a
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: 31 May 2022
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.
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 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:
[index.fields.title]
# Try to find <h1 id="post-title"> if it exists,
# else use the first <h1>
selector = ["h1#post-title", "h1"]
[index.fields.excerpt]
selector = ["p#post-excerpt", "p"]
[index.fields.date]
selector = ["time#post-date", "time"]
extract_attribute = "datetime"
fallback_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...
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, most built-in features can be reimplemented as Lua plugins, and there are page processing hooks.
Soupault is named after the French dadaist and surrealist writer Philippe Soupault because it's based on the lambdasoup library.
Visit 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 macOS. 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/PataphysicalSociety/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 contribute either through GitHub or through Codeberg.
Dependencies (19)
-
camomile
>= "1.0.0" & < "2.0.0"
-
lua-ml
>= "0.9.3"
-
tsort
>= "2.1.0"
-
jingoo
>= "1.4.2"
-
base64
>= "3.0.0"
-
spelll
>= "0.4"
-
odate
>= "0.6"
-
containers
>= "3.6"
-
yaml
>= "2.0.0"
-
ezjsonm
>= "1.2.0"
-
re
>= "1.9.0"
-
fmt
>= "0.8.9"
-
logs
>= "0.7.0"
-
fileutils
>= "0.6.3"
-
otoml
>= "1.0.1"
-
markup
>= "1.0.0-1"
-
lambdasoup
>= "0.7.3"
-
dune
>= "2.0.0"
-
ocaml
>= "4.08"
Dev Dependencies
None
Used by
None
Conflicts (1)
-
result
< "1.5"