https://soupault.app/atom.xml 2026-01-24T00:00:00+00:00 Daniil Baturin and soupault contributors daniil+soupault@baturin.org soupault https://soupault.app/images/soupault_stick_horse.png A static website generator and programmable HTML processor https://soupault.app/blog/migrating-to-soupault-dot-net/ 2026-01-24T00:00:00+00:00 The website has migrated to a new domain: . I plan to eventually let the old soupault.app domain lapse, so please update your links! https://soupault.app/blog/soupault-5.2.0-release/ 2025-11-19T00:00:00+00:00 Soupault 5.2.0 is available for download from and from . It is a small release with one new Lua plugin function and an important bug fix. https://soupault.app/blog/soupault-5.1.0-release/ 2025-06-17T00:00:00+00:00 Soupault 5.1.0 is available for download from and from . It reintroduces the global data in a safer way, adds functions for string case conversion, and also adds an option to strip tags from individual index fields. https://soupault.app/blog/soupault-5.0.0-release/ 2025-04-24T00:00:00+00:00 Soupault 5.0.0 is available for download from and from . It brings built-in Markdown support (in addition to already existing external page preprocessors), a new widget that can translate intermediate HTML elements to real HTML with a template, an option to limit exec and preprocess_element widgets to either UNIX or Windows, and a few new plugin functions. This release also includes a lot of big feature reworks and configuration changes that remove many of the old limitations, inconsistencies, and performance problems. However, they may break some setups and require small adjustments to your configs or plugins, so you should read this post carefully before upgrading. https://soupault.app/blog/soupault-4.11.0-release/ 2024-09-06T00:00:00+00:00 Soupault 4.11.0 is available for download from and from . 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. https://soupault.app/blog/soupault-4.10.0-release/ 2024-04-22T00:00:00+00:00 Soupault 4.10.0 is available for download from and from . 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. https://soupault.app/blog/soupault-4.9.0-release/ 2024-03-20T00:00:00+00:00 Soupault 4.9.0 is available for download from and from . 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. https://soupault.app/blog/soupault-4.8.0-release/ 2024-01-19T00:00:00+00:00 Soupault 4.8.0 is available for download from and from . 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. https://soupault.app/blog/soupault-4.7.0-release/ 2023-09-19T00:00:00+00:00 Soupault 4.7.0 is available for download from and from . 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. https://soupault.app/blog/mistaken-for-malware 2023-07-07T00:00:00+00:00 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. https://soupault.app/blog/soupault-4.6.0-release/ 2023-06-16T00:00:00+00:00 Soupault 4.6.0 is available for download from and from . It improves error reporting for configs with duplicate option names and adds a bunch of useful plugin API functions. https://soupault.app/blog/soupault-4.5.0-release/ 2023-04-17T00:00:00+00:00 Soupault 4.5.0 is available for download from and from . It is a rather unremarkable release, with just a few small improvements and a trivial bug fix. https://soupault.app/blog/soupault-4.4.0-release-and-ssg-caching/ 2023-02-04T00:00:00+00:00 Soupault 4.4.0 is available for download from and from . 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. https://soupault.app/blog/soupault-4.3.1-release/ 2022-11-22T00:00:00+00:00 Soupault 4.3.1 is available for download from and from . It's a very small release that fixes a couple of bugs in the relative links widget. https://soupault.app/blog/soupault-4.3.0-release/ 2022-10-24T00:00:00+00:00 Soupault 4.3.0 is available for download from and from . It adds a few more Lua plugin functions and fixes a few minor bugs. https://soupault.app/blog/soupault-4.2.0-release/ 2022-09-22T00:00:00+00:00 Soupault 4.2.0 is available for download from and from . It adds a way to limit hooks to specific build profiles, introduces a few new command line options, and fixes a couple of bugs. https://soupault.app/blog/soupault-4.1.0-release/ 2022-08-19T00:00:00+00:00 Soupault 4.1.0 is available for download from and from . 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. https://soupault.app/blog/three-years-of-soupault/ 2022-07-15T00:00:00+00:00 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. https://soupault.app/blog/soupault-4.0.1-release/ 2022-05-30T00:00:00+00:00 Soupault 4.0.1 is available for download from and from . 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. https://soupault.app/blog/soupault-4.0.0-release/ 2022-05-14T00:00:00+00:00 Soupault 4.0.0 is available for download from and from . 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. https://soupault.app/blog/soupault-3.2.0-release/ 2021-10-23T00:00:00+00:00 Soupault 3.2.0, is available for download from and from . 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. https://soupault.app/blog/soupault-3.1.0-release/ 2021-08-16T00:00:00+00:00 Soupault 3.1.0, is available for download from and from . 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. https://soupault.app/blog/soupault-3.0.0-release/ 2021-07-19T00:00:00+00:00 Soupault 3.0.0, is available for download from and from . 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. https://soupault.app/blog/soupault-2.8.0-release/ 2021-06-20T00:00:00+00:00 Soupault 2.8.0, is available for download from and from . It adds new options for displaying the default and the effective (i.e. user-defined values plus defaults) configurations and a few bug fixes. https://soupault.app/blog/soupault-2.7.0-release/ 2021-05-12T00:00:00+00:00 Soupault 2.7.0, is available for download from and from . It adds a new wrap widget, ability to disable any widget in the config, and support for multiple build profiles. https://soupault.app/blog/soupault-2.6.0-release/ 2021-04-15T00:00:00+00:00 Soupault 2.6.0, is available for download from and from . It’s a relatively small release with a few bug fixes and one new feature: configurable index entry sorting method. https://soupault.app/blog/soupault-2.5.0-release/ 2021-03-23T00:00:00+00:00 Soupault 2.5.0, is available for download from and from . 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. https://soupault.app/blog/soupault-2.4.0-release/ 2021-01-17T00:00:00+00:00 Soupault 2.4.0, the first release of the new year, is available for download from and from . 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. https://soupault.app/blog/leaving-neocities/ 2021-01-11T00:00:00+00:00 I'll be moving the soupault website from Neocities to another platform. The new site will be available as . 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. https://soupault.app/blog/soupault-2.3.0-release/ 2020-12-18T00:00:00+00:00 Soupault 2.3.0, a winter holidays release, is . 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. https://soupault.app/blog/soupault-2.2.0-release/ 2020-11-29T00:00:00+00:00 Soupault 2.2.0 is . 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. https://soupault.app/blog/soupault-2.1.0-release/ 2020-10-28T00:00:00+00:00 Soupault 2.1.0 is . 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. https://soupault.app/blog/soupault-2.0.0-release/ 2020-09-20T00:00:00+00:00 Soupault 2.0.0 is . 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 . If you run into any bugs or difficulties converting, let me know! https://soupault.app/blog/conference-paper-2020/ 2020-08-26T00:00:00+00:00 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. https://soupault.app/blog/soupault-2.0.0-beta1-release/ 2020-08-24T00:00:00+00:00 Soupault 2.0.0-beta1 is . People familiar with 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. https://soupault.app/blog/soupault-1.13-release/ 2020-07-08T00:00:00+00:00 Soupault 1.13 release is available for . 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. https://soupault.app/blog/soupault-1.12-release/ 2020-05-31T00:00:00+00:00 Soupault 1.12 release is available for . 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. https://soupault.app/blog/soupault-1.11-release/ 2020-04-27T00:00:00+00:00 Soupault 1.11.0 is available for . 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. https://soupault.app/blog/soupault-cd-kit/ 2020-04-01T00:00:00+00:00 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. https://soupault.app/blog/soupault-1.10-release/ 2020-03-25T00:00:00+00:00 Soupault 1.10.0 is available for or installation from the 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. https://soupault.app/blog/soupault-1.9.0-release/ 2020-02-28T00:00:00+00:00 Soupault 1.9.0 is available for or installation from the 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. https://soupault.app/blog/soupault-1.8.0-release/ 2020-01-17T00:00:00+00:00 Soupault 1.8.0 is available for . 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. https://soupault.app/blog/soupault-1.7.0-release/ 2019-12-23T00:00:00+00:00 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. https://soupault.app/blog/soupault-1.6.1-release/ 2019-12-13T00:00:00+00:00 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 or install from opam. https://soupault.app/blog/blogs-and-section-indices/ 2019-12-05T00:00:00+00:00 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. https://soupault.app/blog/soupault-1.6-release/ 2019-11-30T00:00:00+00:00 Soupault 1.6 is now available for . 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. https://soupault.app/blog/enhancing-existing-website/ 2019-11-28T00:00:00+00:00 Today we’ll see how to enhance an otherwise unmodified website with a custom plugin. I picked 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. https://soupault.app/blog/selectors/ 2019-11-13T00:00:00+00:00 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. https://soupault.app/blog/toc/ 2019-11-07T00:00:00+00:00 ToC functionality in static site generators is often far from great, and people are turning to hacks like generated HTML with regular expressions, to a template-based workflow, and even creating 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. https://soupault.app/blog/windows/ 2019-11-04T00:00:00+00:00 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. https://soupault.app/blog/soupault-1.5-release/ 2019-11-01T00:00:00+00:00 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. https://soupault.app/blog/soupault-1.4-release/ 2019-10-27T00:00:00+00:00 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. https://soupault.app/blog/ordering-widgets/ 2019-10-27T00:00:00+00:00 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. https://soupault.app/blog/deleting-elements/ 2019-10-24T00:00:00+00:00 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. https://soupault.app/blog/limiting-widgets/ 2019-10-22T00:00:00+00:00 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. https://soupault.app/blog/errors/ 2019-10-20T00:00:00+00:00 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. https://soupault.app/blog/automation/ 2019-10-16T00:00:00+00:00 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. https://soupault.app/blog/configurable-options/ 2019-10-12T00:00:00+00:00 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. https://soupault.app/blog/why-soupault/ 2019-10-10T00:00:00+00:00 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 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.