# Static website with Soupault and Tufte CSS

<p class="subtitle">First giraffe on <b><time id="post-date">2024-06-30</time></b></p>

<tags>draft, meta</tags>

<section>

<p id="post-excerpt">
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.
</p>

## Soupault

Soupault<sidenote name="soupault"><https://soupault.app></sidenote> is
essentially the answer to all the gripes I have with static site
generators like Jekyll, Hugo, and others.<sidenote
name="soupault-comparison">See the
[comparisons](https://soupault.app/tips-and-tricks/comparison/)</sidenote>
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.  <marginnote
name="jekyll-validate">I considered several times if it would be
worthwhile to implement a post-render HTML validator for
Jekyll</marginnote> 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 CSS<sidenote
name="tufte-css"><https://edwardtufte.github.io/tufte-css/></sidenote>
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
plugin<sidenote
name="quick-links-lua"><https://soupault.app/plugins/#quick-links></sidenote>
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<marginnote name="commonmark">at
least the commonmark processor leaves this markup alone</marginnote>,
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.

</section>