Blog

You can subscribe to the Atom feed to receive updates.

Soupault 4.11.0 release

Last update: 2024-09-06.

Reading time: less than a minute.

Soupault 4.11.0 is available for download from my own server and from GitHub releases. It adds a plugin function for checking if HTML element tree nodes are tree nodes (HTML.is_text()), and fixes and issue with HTML.is_document(). Also, thanks to a lambdasoup update, now there is support for :has() selector in options that accept CSS selectors and another bug fix: namespaces are now correctly preserved in attribute named.

Soupault 4.10.0 release

Last update: 2024-04-22.

Reading time: less than a minute.

Soupault 4.10.0 is available for download from my own server and from GitHub releases. It fixes the complete_page_selector option that unfortunately was broken in recent releases. It also fixes a few bugs with TOML parsing that affected Windows users and adds a new option to the delete_element widget that allows deleting elements only if they don't have certain children inside.

Soupault 4.9.0 release

Last update: 2024-03-20.

Reading time: less than a minute.

Soupault 4.9.0 is available for download from my own server and from GitHub releases. It is a small release that includes Lua plugin API for cryprographic hash functions (MD5, SHA-1, SHA-256/512, and BLAKE2), a couple of function aliases, and a new hook that runs before any pages are processed.

Soupault 4.8.0 release

Last update: 2024-01-19.

Reading time: 5 minutes.

Soupault 4.8.0 is available for download from my own server and from GitHub releases. It is a small release that fixes a bug with parsing HTML of page bodies that could cause weird behavior when tags like style were found in pages, makes the index entry data available to all hooks past the indexing stage, and adds a small helper function — HTML.inner_text(). However, there are big plans for the next release (whenever it is made) — read on for details.

Soupault 4.7.0 release: CSV support, global shared data, post-build hook, and more

Last update: 2023-09-19.

Reading time: 6 minutes.

Soupault 4.7.0 is available for download from my own server and from GitHub releases. It adds support for loading CSV files, a variable for passing global data between plugins and hooks, a way to determine which two-pass workflow pass is a plugin is executed for, and a few more improvements.

Mistaken for malware

Last update: 2023-07-07.

Reading time: 15 minutes.

For a few days a couple of weeks ago, soupault's website was unavailable at the soupault.app address to users of Quad9 and some other public DNS services. The reason was that certain security service and software vendors incorrectly classified it as malicious. Now that the situation is resolved, it's time to talk about my experience of interaction with those vendors.

Soupault 4.6.0 release

Last update: 2023-06-16.

Reading time: less than a minute.

Soupault 4.6.0 is available for download from my own server and from GitHub releases. It improves error reporting for configs with duplicate option names and adds a bunch of useful plugin API functions.

Soupault 4.5.0 release

Last update: 2023-04-17.

Reading time: 4 minutes.

Soupault 4.5.0 is available for download from my own server and from GitHub releases. It is a rather unremarkable release, with just a few small improvements and a trivial bug fix.

Soupault 4.4.0 release and a review of cache implementations in static site generators

Last update: 2023-02-04.

Reading time: 13 minutes.

Soupault 4.4.0 is available for download from my own server and from GitHub releases. Its major change is the implementation of caching for the outputs of page preprocessors and preprocess_element widgets that can make repeated builds several times faster for sites that call external tools a lot. Somewhat unusually for a release post, I included a detailed description of the implementation and comparison with other SSGs, so this post may also help other SSG developers.

Soupault 4.3.1 maintenance release

Last update: 2022-11-22.

Reading time: 2 minutes.

Soupault 4.3.1 is available for download from my own server and from GitHub releases. It's a very small release that fixes a couple of bugs in the relative links widget.

Soupault 4.3.0 release

Last update: 2022-10-24.

Reading time: less than a minute.

Soupault 4.3.0 is available for download from my own server and from GitHub releases. It adds a few more Lua plugin functions and fixes a few minor bugs.

Soupault 4.2.0: profile option for hooks, new command line options, and bug fixes

Last update: 2022-09-22.

Reading time: 2 minutes.

Soupault 4.2.0 is available for download from my own server and from GitHub releases. It adds a way to limit hooks to specific build profiles, introduces a few new command line options, and fixes a couple of bugs.

Soupault 4.1.0: asset processors, post-save hook, and more

Last update: 2022-08-19.

Reading time: 3 minutes.

Soupault 4.1.0 is available for download from my own server and from GitHub releases. It continues the extensibility improvement trend of 4.0.0 and adds two new mechanisms: post-save hooks and asset processors. Additionally, release archives now include a changelog file.

Three years of soupault

Last update: 2022-07-15.

Reading time: 8 minutes.

Three years ago, on 2019-07-15, I released the first public beta of soupault. There is no anniversary release this time, so I'm just using it to look back and reflect on the project history. There will be a release, of course, but not right now.

Soupault 4.0.1 maintenance release

Last update: 2022-05-30.

Reading time: 2 minutes.

Soupault 4.0.1 is available for download from my own server and from GitHub releases. It's a small maintenance release that fixes two bugs: one introduced by the post-index hook implementation, and another one in indexing withhout clean URLs.

Soupault 4.0.0: as extensible as Jekyll, still statically linked

Last update: 2022-05-14.

Reading time: 25 minutes.

Soupault 4.0.0 is available for download from my own server and from GitHub releases. It introduces page processing hooks, Lua index processors (which allow creating taxonomies and paginated indices), a new option to make the site index available to content pages, an option to process certain pages before all other, a way to mark certain index fields as required, and a bunch of new Lua plugin API functions. Well, and a few bug fixes, of course.

Soupault 3.2.0 release: persistent variables for plugins, checking for selector matches, and more

Last update: 2021-10-23.

Reading time: 4 minutes.

Soupault 3.2.0, is available for download from my own server and from GitHub releases. It features variables that are persistent between plugin runs, new functions for checking whether an HTML element matches a CSS selector, and some bug fixes.

Soupault 3.1.0 release

Last update: 2021-08-16.

Reading time: 3 minutes.

Soupault 3.1.0, is available for download from my own server and from GitHub releases. It’s a small quality of life and bugfix release. It adds plugin functions for platform-independent UNIX/URL path manipulation, and new functions for ordered iteration through tables. The ToC widget now has an option to ignore headings that match certain selectors. Finally, specifying a widget twice by accident in the after option no longer causes a false positive dependency cycle detection.

Soupault 3.0.0 release

Last update: 2021-07-19.

Reading time: 5 minutes.

Soupault 3.0.0, is available for download from my own server and from GitHub releases. It uses a new, fully standard-compliant TOML parsing library, and also adds new features, such as colored log headers, Lua plugin functions for loading TOML and YAML data, and a more precise selector for the title widget. The 3.0.0 version shouldn’t scare you: the breaking change is that the old library used to allow certain invalid TOML syntax while the new one does not, so you are unlikely to be affected and if you are, it’s an easy fix—but technically it’s still a breaking change and must be marked as such.

Soupault 2.8.0 release

Last update: 2021-06-20.

Reading time: 3 minutes.

Soupault 2.8.0, is available for download from my own server and from GitHub releases. It adds new options for displaying the default and the effective (i.e. user-defined values plus defaults) configurations and a few bug fixes.

Soupault 2.7.0 release

Last update: 2021-05-12.

Reading time: less than a minute.

Soupault 2.7.0, is available for download from my own server and from GitHub releases. It adds a new wrap widget, ability to disable any widget in the config, and support for multiple build profiles.

Soupault 2.6.0 release

Last update: 2021-04-15.

Reading time: 2 minutes.

Soupault 2.6.0, is available for download from my own server and from GitHub releases. It’s a relatively small release with a few bug fixes and one new feature: configurable index entry sorting method.

Soupault 2.5.0 release

Last update: 2021-03-23.

Reading time: 4 minutes.

Soupault 2.5.0, is available for download from my own server and from GitHub releases. New features in this release include an option to preserve the original whitespace in HTML pages (i.e. disable pretty-printing) and two new built-in widgets for rewriting internal links: relative_links and absolute_links. There are also some bug fixes and quality of life improvements.

Soupault 2.4.0 release

Last update: 2021-01-17.

Reading time: 7 minutes.

Soupault 2.4.0, the first release of the new year, is available for download from my own server and from GitHub releases. It offers a few bug fixes, new plugin functions (e.g. a new Value.is_nil etc. function family you can use for explicit type checking), and new options. Among others, threre’s now an option to mark some directories as "hand-made clean URLs" rather than sections to bundle a page with its assets. At the end there’s a brief discussion of the plans for 2021.

Leaving Neocities

Last update: 2021-01-11.

Reading time: 5 minutes.

I'll be moving the soupault website from Neocities to another platform. The new site will be available as www.soupault.app. The process should be more or less seamless, and should not affect any functionality. If you are interested in my motivation, read on. If you are wondering if I came to hate Neocities, then no, by no means—it's not a bad platform, and I'm not advocating against it. It's my choice and it should not influence yours.

Soupault 2.3.0 release

Last update: 2020-12-18.

Reading time: 3 minutes.

Soupault 2.3.0, a winter holidays release, is available for download. The main highlight is a bunch of new plugin functions for dealing with files and Base64 data. There’s also a bug fix related to the profile option and a couple of behaviour improvements. Also, the macOS target is now named macos-x86_64 to reflect the existence of macOS on ARM64. There are no prebuilt binaries for it, so if you’ve got an ARM64 Mac, you’ll need to build from source or rely on its x86 compatibility layer.

Soupault 2.2.0 release

Last update: 2020-11-29.

Reading time: 7 minutes.

Soupault 2.2.0 is available for download. It brings support for settings shared between plugins, makes it easier to work with tables from Lua code, adds some date/time manipulation functions, and fixes a few bugs. This release also removes support for 32-bit Windows.

Soupault 2.1.0 release

Last update: 2020-10-28.

Reading time: 5 minutes.

Soupault 2.1.0 is available for download. It's a feature expansion release that adds some new options and makes existing features more flexible. Among them are ability to preserve original page doctype, support for multiple selectors in inclusion widgets, new ToC anchor slugification options, and more. This release also introduces 64-bit Windows support, and may be the last release to support 32-bit Windows.

Soupault 2.0.0 release

Last update: 2020-09-20.

Reading time: 8 minutes.

Soupault 2.0.0 is available for download. I believe it’s now stable enough for a public release. Its config format is incompatible with earlier 1.x.x releases, which is why the major version number has increased. I understand that config format change is quite a hassle for users, so I made a convertor. If you run into any bugs or difficulties converting, let me know!

Imaginary conference paper

Last update: 2020-08-26.

Reading time: 5 minutes.

I was planning to give a talk about Soupault at an online conference, but the conference ended up completely cancelled, so the paper I wrote for it ended up unused. If you know of an upcoming conference that may be interested in it, let me know. Otherwise, it can remain a good introduction to the project I suppose.

Soupault 2.0.0-beta1 release

Last update: 2020-08-24.

Reading time: 8 minutes.

Soupault 2.0.0-beta1 is available for download. People familiar with semantic versioning likely have a bad feeling already. Yes, it means what you think it means: there are breaking changes that make soupault 2.0.0 incompatible with older releases. Those changes are necessary to fix old design mistakes and make some useful improvements. I made an effort to simplify the migration as much as possible. Please read this post carefully before upgrading.

Soupault 1.13.0 release

Last update: 2020-07-08.

Reading time: 11 minutes.

Soupault 1.13 release is available for download. This release solves two long-standing problems with the plugin API: lack of an easy way to generate a custom table of contents, and lack of a way to pass arbitrary values to plugins from the config file.

Soupault 1.12.0 release

Last update: 2020-05-31.

Reading time: 3 minutes.

Soupault 1.12 release is available for download. It’s a pretty small release, with just two essential changes. I haven’t had much time last month so big things from the roadmap aren’t there yet. What is there is better reporting of missing/misspelt widget dependencies and a way to properly loop through node’s children.

Soupault 1.11.0 release

Last update: 2020-04-27.

Reading time: 4 minutes.

Soupault 1.11.0 is available for download. It's not a very big release, but it adds some new features, including support for multiple page templates, ability to extract attribute values as metadata, and new plugin API functions for working with element attributes.

Now you can make your own soupault CD

Last update: 2020-04-01.

Reading time: less than a minute.

It was once common for open source projects to sell CDs to make some money and help people with slow Internet connections to get the software. Fast and cheap Internet access made physical media obsolete, but I'm pretty sure some people miss classic distribution methods. Of course it would be impractical to make and sell CDs, but now you can make your very own soupault CD with a DIY CD kit. It includes printable keep case cover and CD label, so all you need is a blank CD, color printer, and scissors.

Soupault 1.10.0 release

Last update: 2020-03-25.

Reading time: 6 minutes.

Soupault 1.10.0 is available for download or installation from the opam repository. It's not a very big release, but there are some bug fixes and improvements I'd like to make available to the users before starting to work on big internal changes. New features you will find in this release include automatic plugin discovery, correct handling of files without extensions, and new plugin functions.

Soupault 1.9.0 release

Last update: 2020-02-28.

Reading time: 3 minutes.

Soupault 1.9.0 is available for download or installation from the opam repository. It now offers a --index-only option for people who want to extract site metadata to JSON and stop at that. There are also multiple improvements in the plugin API and the preprocess_element widget support, as well as bug fixes.

Soupault 1.8.0 release, with improved plugin support

Last update: 2020-01-17.

Reading time: 4 minutes.

Soupault 1.8.0 is available for download. This release is focused on improving plugin support. First big improvement is that Lua plugin execution errors are treated exactly like all other errors: in strict mode, they fail the build. There’s also a bunch of new plugin functions.

Soupault 1.7.0 release

Last update: 2019-12-23.

Reading time: 7 minutes.

Soupault 1.7.0 is available for [download](/#downloads). With this new version, you can pipe the content of elements through any external preprocessor (e.g. for syntax highlighting), use multiple different index “views”, and specify default values for custom index fields.

Soupault 1.6.1 maintenance release

Last update: 2019-12-13.

Reading time: less than a minute.

Soupault 1.6.1 is a small maintenance release that fixes an issue with <noscript> tags inside includes and HTML snippets used by include and insert_html widgets. Those tags are now parsed correctly. You can download the updated executables from files.baturin.org/software/soupault/1.6.1/ or install from opam.

Making section indices and blogs

Last update: 2019-12-05.

Reading time: 8 minutes.

This website and the blog are made with soupault, quite obviously. How exactly the blog is made? While soupault doesn't include any blog functionality, it allows you to extract metadata from existing pages and either render it using a built-in index generator or feed it to an external script.

Soupault 1.6 release

Last update: 2019-11-30.

Reading time: 6 minutes.

Soupault 1.6 is now available for download. The first big improvement is a built-in index generator that supports mustache templates, so you can make blog feeds and lists of pages without any external scripts now. The second improvement is a bunch of new plugin API functions that should make writing plugins easier and add more capabilities.

Enhancing an existing site with a custom plugin

Last update: 2019-11-28.

Reading time: 6 minutes.

Today we’ll see how to enhance an otherwise unmodified website with a custom plugin. I picked Neocities Districts website for a showcase. I’m not affiliated with Districts, I just like their website, but I also think it’s a bit hard to navigate and could really benefit from alphabetic indices. Let’s see how it could be done with soupault. Its authors are free to reuse the solution if they like it, of course. The result will be fully static and will not need any JS, so it will work even in text browsers and with JS disabled.

Using selectors

Last update: 2019-11-13.

Reading time: 7 minutes.

Soupault turns the traditional HTML processor workflow upside down: instead of inserting a placeholder like {{header}} or {{content}} in your page, you point it at a specific element in your page using CSS selectors. That’s what allows it to work with unmodified websites and find elements regardless of their exact location in the page. It also saves you learning time since everyone who ever wrote a CSS stylesheet already knows the basic selector syntax. However, there are less well-known features of the CSS standard that may help you find elements with better precision—let’s take a closer look at them.

Tables of contents

Last update: 2019-11-07.

Reading time: 6 minutes.

ToC functionality in static site generators is often far from great, and people are turning to hacks like parsing generated HTML with regular expressions, adding an HTML parser to a template-based workflow, and even creating external tools to fix buggy output. I'm clearly not the only one who wants good tables of contents, so I set out to make it as close to perfect as possible. My understanding of perfect here is robust and configurable. Let's how it works and how to setup it.

Using soupault on Windows

Last update: 2019-11-04.

Reading time: 2 minutes.

I don't use Windows myself. There are, however, many people who do, and I want to make my programs available to them. I tried to make soupault work on Windows exactly like it works on UNIX, and all functionality is available there, with only a few minor differences you should be aware of. If you are not using any preprocessors or external scripts, same configs should work on all systems without adjustments.

Soupault 1.5 (it can work with unmodified websites as an HTML processor now)

Last update: 2019-11-01.

Reading time: 6 minutes.

Soupault 1.5 is easy to try out without modifying any existing page. It's now able to detect if a file is a page body or a complete page. Page bodies are inserted in the template, but complete pages are just processed by widgets/plugins. Moreover, there's now an “HTML processor mode” when it needs no template at all. Now it's much easier to make websites where many pages have a unique layout, or use soupault to automatically enhance an existing site, e.g. inject a viewport meta tag or a table of contents into every page, or add an autogenerated list of all pages.

Widget pipelines and ordering

Last update: 2019-10-27.

Reading time: 3 minutes.

One limitation of classic static site generators is that output of a template is generally final and cannot be processed further. They assemble pages by filling the blanks. In some implementations they can set variables, but they cannot create other templates. Soupault's widgets, however, form a pipeline where output of one input can be used as input for another. You can also explicitly order the widgets to make sure they run when their input is available.

Soupault 1.4 release

Last update: 2019-10-27.

Reading time: 5 minutes.

I've released soupault 1.4. It's not a big release, but it offers some convenience features that hopefully make it easier to work with.

Deleting elements

Last update: 2019-10-24.

Reading time: 2 minutes.

To my knowledge, soupault is the only website generator that can delete things from pages. With a generator based on a template processor you can conditionally include something in the page or not, but if it's already in the page, you can't do anything about it. Soupault opens a new era for website management: now you can delete anything you want, including the <body> element. First let's see how it's done and then discuss the use cases for deleting elements.

Doing things only to some pages

Last update: 2019-10-22.

Reading time: 4 minutes.

Soupault is meant to be a website generator for Web 1.0. One of the key freedoms the Web 2.0 approach took away is the freedom to make different pages look different. To live up to the Web 1.0-friendly promise, a tool must make it easy to do again. Soupault includes a number of features to make it easier.

Errors and error handling

Last update: 2019-10-20.

Reading time: 4 minutes.

Like every static website generator, soupault is a non-interactive program that cannot ask the user what to do if something goes wrong. Most errors are caused by configuration mistakes, so the user would want to fix the configuration anyway, rather than make a one-time correction. With non-interactice programs, it's especially important to have a clear mental model of what the program is doing and where it may fail.

Workflow automation

Last update: 2019-10-16.

Reading time: 3 minutes.

Soupault intentionally doesn't have a built-in web server, deployment automation, or a snake game (though a snake game may be added in future versions, stay tuned). That's the UNIX philosophy: do one thing and do it well. The big idea is to provide configurable workflows rather than force a workflow on you. Here's my workflow that you can use as an example if you like it, or disagree with and make your own—the choice is yours.

Tweaking the configuration

Last update: 2019-10-12.

Reading time: 5 minutes.

For simplicity, soupault docs (and these posts) often talk about directories and behaviour as if they are set in stone, but in fact those are just defaults. In reality, most options are configurable and you can change them if you want to. Today we'll walk through the options from the default config generated by soupault --init and discuss what they do and why you may want to change them.

Why soupault?

Last update: 2019-10-10.

Reading time: 9 minutes.

There are so many static site generators already that another one needs a pretty good justification. I mainly made soupault for my own use, in fact it has grown out of a set of custom scripts that used to power the baturin.org website. Still, if I'm making it public, I may as well want to explain the decisions behind it and reasons why anyone else may want to use it.