Blog

You can subscribe to the Atom feed to receive updates.

Leaving Neocities

Last update: 2021-01-11.

Reading time: 2 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: less than a minute.

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: 3 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: 2 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: 4 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: 2 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: 4 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: 5 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: less than a minute.

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/misspellt widget dependencies and a way to properly loop through node's children.

Soupault 1.11.0 release

Last update: 2020-04-27.

Reading time: 2 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: 3 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: less than a minute.

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: 2 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: 3 minutes.

Soupault 1.7.0 is available for download. 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: 4 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: 3 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: 3 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: 3 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: 3 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: less than a minute.

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: 3 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.

Soupault 1.4 release

Last update: 2019-10-27.

Reading time: 2 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.

Widget pipelines and ordering

Last update: 2019-10-27.

Reading time: less than a minute.

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.

Deleting elements

Last update: 2019-10-24.

Reading time: less than a minute.

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: 2 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: 2 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: less than a minute.

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: 2 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: 4 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.