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
- What Is Soupault?
- Why Soupault? Part One: Themes
- Why Soupault? Part Two: Plugins And Scripts
- Why Soupault? Part Three: I Can't Believe It's Not Dynamic!
- Why Soupault? Part Four: Any Format You Like
- Why Not Soupault?
- Footnotes And References
→ 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.
→ Why Soupault? Part One: Themes
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:
- My atom feed is generated with a Lua plugin, as is my sitemap. 11 12
- You might notice the word "Blog" at the top of this page is boldened and underlined; that's the Highlight Active Link plugin in action. 13
- The footnotes you may have noticed peppered throughout this and other posts are also from a Lua plugin. 14
- The table of contents at the top of this and other posts - you guessed it: Lua plugin. 15
- You can check the source of this page to see how it all works - there's a link at the bottom of the page. Yes, that too is a Lua plugin! 17
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.
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:
- You want something with a graphical user interface. Soupault is a command-line program, so if you're someone who is used to Frontpage, Dreamweaver, or similar softwares, this may be a barrier to entry for you. 24
You're already using some other SSG/CMS/etc, and migrating is hard.
- When I migrated this blog from being Django-based with an SQL database to Soupault, I had to handle converting blog posts from SQL to raw HTML and saving them in a way that Soupault could use them. It wasn't extremely difficult, but it wasn't trivial either, and did require some careful planning.
- Migrating from another SSG shouldn't be hard in theory. You could build the site into HTML, turn "generator mode" off.. Your site is now a Soupault project. 25
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
2 Some other sites I've built with Soupault: mousikofidi.info, wem.hristos.co, gr4h.co (WIP), and dimension-warrior.blackholegate.com (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.
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
18 This is the python script, which uses pystache to do templating.
19 This is the relevant part of my
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.