Soupault: One Year In And Beyond


Some time ago, I decided to convert my Django-based blog to a static website. At the time, I wrote a little bit about my motivations but that piece was light on the technical details of "why Soupault". In this piece, I'll go over those details in the hope that more folks will give Soupault a look!

Full Disclosure

I want to first mention that I am a Soupault code contributor, plugin author, and I consider the creator to be a personal friend of mine. 1 I've created more than a handful of websites with Soupault, and I plan to use it for future projects when possible. 2 These things make me somewhat biased, so keep that in mind as you read!

What Is Soupault?

Soupault is a static site generator (hereby referred to as an SSG), which means it is a piece of software that produces static HTML files intended to be served as a website.

As SSGs go, Soupault is a bit more powerful than that, though. Unlike most SSGs which try to hide layers such as HTML or CSS from you (more on that in a bit), Soupault embraces and gives you full access to them; use selectors in the same way as you would in your HTML, CSS, or Javascript. It feels idiomatic, as if it's just part of the HTML-processing experience. Best of all, nothing really feels magical this way, and I'm not worried about problems with abstractions.

Why Soupault? Part One: Themes

When you look at SSGs, a common trait among them are "themes" or some way of attempting to abstract away HTML, CSS, and possibly even Javascript. On the surface it might seem nice, especially if you don't fancy coding in those languages. It could very well work out for those folks.

But you may run into problems, usually, when you start to try and customize things - or if your SSG updates and breaks compatibility with your theme. 3 4 5 6 7 This, in my opinion, is a shining point of Soupault: that it has no notion of "themes". That's right, a lack of a feature is itself a feature! You want to hear more? Okay!

Instead of opaque themes, Soupault enables you to easily leverage HTML templates so that you can produce DRY 8 layouts and styles. You can even selectively do things with widgets (more on that in a bit)!

If you're not looking to avoid HTML/CSS/JS at all costs this ends up paying off in the long run and offers much greater flexibility than a theme could by design.

Why Soupault? Part Two: Plugins And Scripts

Soupault also sports a Lua scripting API, as well as a mechanism for piping in and processing output from scripts. This is probably the most complex part of Soupault, but also the most powerful. It's these features that allow me to have a fully static website that has a dynamic look and feel.

Lua Plugins

Soupault has a public Lua plugin directory with several very useful plugins, including many that are used on this very website! 9 10

If you want to extend a plugin or write your own, consult the Plugin API docs for a rundown of what all you can do with it. I found the public plugin directory to be a great resource for working plugin code to reference while building my own plugins.

Here's some examples of nifty things I'm doing with plugins:


When you need something a little more powerful, you can use external scripts written in any language to produce HTML that is consumed and processed by Soupault.

On this website (at least, as of the time of this writing) the main index page has a partial blog post list. This is achieved through an external python script and Soupault's own indexing capabilities. 18 19 20

Why Soupault? Part Three: I Can't Believe It's Not Dynamic!

It's very possible to achieve a "dynamic" look and feel that's common with traditional non-static websites.

Blog Style

The indexing capabilities mentioned above are powerful enough on their own to produce a full "blog post" index, without any scripts or plugins. As of this writing, such a page can be found on this website's "Blog" page.

This website's soupault.conf has all the details, but in a nutshell: I first define index fields that will provide context to my index, then I define the index itself as well as a simple HTML snippet to use. I'm using a regular expression to select which "blog posts" to include in the index.

The "Tips and tricks" section of the Soupault website has several nice resources on how to do various things with Soupault, including some helpful usage pattern examples, and a comparison table that lists differences between Soupault and other popular SSGs. 21


You might think that searching is out of the question with a static website, but that isn't the case! Take for example the Portmod project's OpenMW Mod Repository, which is built using Soupault and leverages Stork for searching.

Of course this isn't specific to Soupault, but if you're coming from a system with a database that makes stuff like search easy, you may be wondering "can I still have that?". The answer is yes!

Why Soupault? Part Four: Any Format You Like

This is an aspect of Soupault that I myself don't utilize much since I prefer to work directly with HTML and friends, however: any format that can be converted to HTML is usable with Soupault.

Page preprocessors can be configured using any arbitrary command, so it is theoretically possible to use a huge variety of formats if desired. 22

Additionally the converted output can and will be usable to Soupault, so you can apply widgets and scripts to them as desired.

If you prefer Markdown, Wiki Markup, Rich Text Format, Org-mode, or any other one of many many different formats, Soupault has you covered. Anything you can convert to HTML outside of Soupault can be done within it.

This is probably nice for folks who would be coming from other SSGs that use Markdown or some other format; it's possible that a lot of that would carry over into a Soupault project.

Why Not Soupault?

Soupault is so excellent, so powerful, that I strongly recommend it for any project that can exist as a static website. That being said, I can think of a few reasons that Soupault might not be right for you:


The "Soupault Way" is somewhat different from most other SSGs' usage patterns, but it ends up (for me, at least) being not only less work overall, but it also has (again, for me at least) less friction for actually interacting with my website. Really, the only barrier right now is simply me sitting down and writing something that's decent.

The widget/plugin/scripts systems afford me the flexibility to do a lot of things, and in the future I'd like to do even more. For example, it'd be nice to bring categories back to the blog.

In the end, there are a lot of SSGs out there, and more being made all the time. Soupault is still somewhat rare with its focus on HTML processing and manipulation, but I think it's a great approach that enables powerful new patterns that feel idiomatic in my HTML editing stack.

Footnotes And References

1 Hey, Daniil!

2 Some other sites I've built with Soupault:,, (WIP), and (also WIP)

3 Hugo-Icarus: "The original Hugo Icarus theme has been unmaintained for years, and as Hugo upgraded, some features broke (such as front-page post listing, recent posts, and post counts). This version fixes such issues."; this indicates a history of breakage with Hugo.

4 Another broken Hugo theme

5 .. Another broken Hugo theme

6 .... And another broken Hugo theme

7 A cautionary tale about using Hugo, mainly looking at themes breaking but other things are covered as well



10 My plugins, as of this writing

11 soupault.conf#L90-104

12 soupault.conf#L106-112

13 soupault.conf#L122-128

14 soupault.conf#L139-151

15 soupault.conf#L170-184

16 soupault.conf#L194-225

17 soupault.conf#L130-137

18 This is the python script, which uses pystache to do templating.

19 This is the relevant part of my soupault.conf.

20 Soupault's documentation on "Metadata extraction and rendering" covers the topic of indexes quite well.


22 The official reference on page preprocessors.

23 Though even in this case you are likely still writing YAML or some other kind of markup.

24 Snicker if you want, but as I understand it there are indeed folks who still use these and other older "publishing" softwares. These users are absolutely folks who could adopt Soupault, in theory.

25 Soupault reference and overview, mentioning what "generator mode" actually is. The Getting started: HTML processor page is another good resource for this.

This page was last modified on: 2021-06-05