Peach Tea - Thank You, Soupault

Thank you, Soupault 🙏

For the joy you have brought to my time building static websites.

Quick praise for static sites 👏

To their courage in the face of unknown visitors & their rememberance of how simple things could be if we let them be

Sure they don’t remember our birthdays but there’s something quite humbling about that

The internet is a crazy and crowded place and I am very grateful for these beacons of
just works 👍 / simply doesn't 👎

in this all-too-large sea of
works on my machine 🤷 / dang, not for me 😦

Double, double toil and trouble 🧹

For context, I maintain (and hopefully improve) a number of static sites on the internet using vanilla HTML, CSS, and Javascript. Knowing these tools well I’ve found this to be a fine way to work - after all there’s no versioning or bundling or minification to be concerned with.

While this way of working is reasonable it also leaves a bit to be desired; updating shared components with find and replace is clumsy and editing between tags is not incredibly inviting. I spent some time looking into popular options for reducing these sorts of unpleasantries and found that many of them were just too involved for the problems I was facing (something something, nail and sledgehammer). More specifically I looked into Jekyll, Gatsby, and Hugo. Being familiar with Next.js, I also considered that but decided against involving a node runtime in these sites.

A minimal & useful tool 🛋️

After suspending my search for a while, I came across soupault – a command-line tool described as a “robotic webmaster”. I decided to try it out and to my pleasant surprise after a short while had some of my pages working with it. What I quickly realized about this tool is that its power lies in the way it plays so well with others.

Before we get into what it looks like to work with soupault let’s take a look at some key characteristics of this system:

Content is written in markdown (+ html where needed)
Site is built using a preprocessing & templating pipeline
Buildable with make
One-command publishing to the world wide web

This system works well for me for a number of reasons:

These sites tend to have a large amount of text and media content – markdown makes describing that content much easier
Content and cardinality of pages changes a lot but the context of all pages changes rather infrequently
Building with the make command opens up the flexibility to build on file change, or at an interval
It’s awesome to be able to stay in the command line to deploy the site.

I must admit that system design is rather interesting to me and I will spend time redesigning a system with nothing obvious to show for it just because I enjoy it. This is to say there was a bit of a overhead in understanding how soupault worked, and then migrating my pages to be in the new format. After everything, I found it very rewarding and entirely worth it in the end.

Site architecture 🏛️

soupault is shipped as a standalone binary which reads ./soupault.conf and looks like this:

# /soupault.conf
[settings]  
  # take the files in site/ and build them into public/
  site_dir = "site"
  build_dir = "public"

  # Replace content in the <main></main> tag of the template page
  default_content_selector = "main"
  default_content_action = "replace_content"

# Preprocessors are ran before templating is applied, for the specified file types
[preprocessors]
  # Run cmark on `.md` files to convert them to html
  md = "cmark"

This setup requires a template page, which by default points to templates/main.html:

<!-- /templates/main.html -->
<html lang="en" dir="ltr">
  <head>...</head>
  <body>

    <header><a href="/">peachtea.xyz</a> / <span id="breadcrumb"></span></header>

    <!-- Generated Content will be placed here -->
    <main></main>

    <!-- Thank you goatcounter !-->
    <script src="/js/count.js"></script>
  </body> 
</html>

Essentially soupault will run the specified preprocessor for each file type before putting the HTML it generates into the <main> tag of the template. I will let your imagination run wild with how this could be extended to use all sorts of preprocessors for any file type you want (.jpg, .csv, .txt) to get web pages just by dropping a file into a directory. How lovely!

As an added bonus, since cmark and soupault are both self-contained binaries, you can bundle the build tools for the site with the code.

The flow 🌊

The simplicity of working in this environment brings me joy – the workflow is best demonstrated by the project’s Makefile:

# /Makefile
all:
	./bin/soupault.sh

serve:
	./serve.sh & ./make_sleep.sh 10

commit:
	git add .; git commit -m "make commit"; git push origin main;

publish:
  # Publish site to the world wide web

There are some shell scripts here for switching soupault binaries based on the OS, starting a server, and rebuilding the site on an interval. Admittedly this commit command makes the git history of the repo rather useless at points but it’s a small price to pay.

`// todo:` 📝

Coming back to this, I’ve already tackled a lot of the TODOs but there are still some things I’d like to improve in this system. For instance I’d like to use a better system for declaring metadata, the current strategy is a little clumsy with writing a smaller <head>...</head> in the markdown.

Bye 👋

Thanks for reading! I hope you have some use cases for soupault as well and get to experience working with this wonderful tool ❤️