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. ¹ I've created more than a handful of websites with Soupault, and I plan to use it for future projects when possible. ² 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 ⁸ 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. ¹³
• The footnotes you may have noticed peppered throughout this and other posts are also from a Lua plugin. ¹⁴
• The table of contents at the top of this and other posts - you guessed it: Lua plugin. ¹⁵
• I selectively insert elements based on page content for several purposes, including: Asciinema assets, extra CSS for syntax highlighting code snippets, only loading Javascript on pages that need it, and more. ¹⁶
• 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! ¹⁷

→ Scripts

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. ²¹

→ Searching

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. ²²

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 really don't want to write any HTML, CSS, or Javascript. Other SSGs that use "themes" can in theory allow you to get away with this. ²³
• 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. ²⁴
• 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. ²⁵

→ Conclusion

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

Source link for this page