Static website with Soupault and Tufte CSS

The technology behind this website has changed a few times. In this write-up I want to describe the current implementation using Soupault and Tufte CSS.

Soupault

Soupaulthttps://soupault.app is essentially the answer to all the gripes I have with static site generators like Jekyll, Hugo, and others.See the comparisons Soupault works with HTML trees, not templated text files. There is still a template system, but the templates themselves are valid XML (if not HTML) and do not have to be this weird mix of HTML and some template language. When I used Jekyll it always bothered me that I would not know if the end result would be valid HTML before all templates had been stitched together with some content. ⊕I considered several times if it would be worthwhile to implement a post-render HTML validator for Jekyll Parsing templates and content into HTML trees first, then fusing them together eliminates an entire class of problems, because any syntactical errors would be caught parsing the sources.

Tufte CSS

I think it is fair to say that discovering Tufte CSShttps://edwardtufte.github.io/tufte-css/ was love at first sight. This styling is just pretty. The aesthetics truly hit a sweet spot for me. For reading on a monitor, I prefer serif fonts and the ETBook font just looks great.

Tufte CSS solves a problems that has always been a headache for me. I like adding links and references to my writing, in part because I like writing about things I’m learning and want to keep references around. If I were producing a PDF I would use footnotes, but footnotes on a website never really made sense to me, because you end up jumping up and down on a page to follow them. I also am not a fan of sprinkling links in the body text, I feel like it’s adding too much visual noise and distracts the reader. Side notes and margin notes as implemented in Tufte is a great solution to this, it allows me to add references where I want without introducing too much noise in the body text. I have converted most links to sidenotes.

Soupault & Tufte

As much as I can, I try to preserve the ability to read the source text files (Markdown) and have the HTML rendering “just” be a nice presentation of the text.

In this regard, Tufte CSS presents a challenge when it comes to sidenotes and margin notes. To render a single sidenote, three HTML elements must be added:

<label for="mn-demo" class="margin-toggle">&#8853;</label>
<input type="checkbox" id="mn-demo" class="margin-toggle"/>
<span class="marginnote">
  This is a margin note. Notice there isn’t a number preceding the note.
</span>

For the note to appear in the right spot in the HTML page, these elements cannot be hidden away somewhere in the markdown. They need to sit in the right place. Forcing this into the markdown really hurts the legibility of the raw text.

Fortunately, this is where Soupault can show its strength! We can define fake HTML elements and have soupault replace those with the right HTML during processing. I cribbed the existing quick-links.lua pluginhttps://soupault.app/plugins/#quick-links and extended it to support the following elements.

<sidenote name="[name]">[content]</sidenote>
<marginnote name="[name]">[content]</marginnote>

The difference between the two is that <sidenote> are numbered whereas <marginnote> are not. The [name] must be unique for the given type, the [content] is what should be displayed in the margin. Writing in Markdown, these elements can be inserted inline, the Markdown processor leaves it alone⊕at least the commonmark processor leaves this markup alone, but soupault can post-process it. This solution strikes a good balance between leaving the raw Markdown readable while allowing some stylish sidenotes to be inserted in the HTML.

Tufte CSS also wants all the contents of an article to go in one or more <section> elements. This has made me sprinkle <section></section> in all the markdown files. It’s a compromise, but I think it’s acceptable.