◇ The realm’s secrets

◇ Generating HTML

I used the existing html generator from the jotdown crate as a starting point, but made heavy modifications to the code in order to support the features my heart longed for (like the example above!).

Although repeated write! calls work well enough for generating simple HTML, I felt the need for a more robust templating system when creating more complex elements. The system I ended up with works pretty well, although a bit simplistic feature-wise (which is by design, copium). For instance, the aforementioned character asides are powered by this template:

<aside class="aside" aria-labelledby="{{id}}">
  <div class="aside-header">
    <img
      alt="{{character}}"
      src="/assets/icons/characters/{{character}}.webp"
    />
    <h3 id="{{id}}">{{title}}</h3>
  </div>

  {{content}}
</aside>

The template text gets embedded into the final binary (using incude_str!), then gets parsed at most once (using an OnceCell), into what essentially boils down to a list of ranges where content should be inserted:

struct Stop<'s> {
  label: &'s str,
  start: usize,
  length: usize,
}

pub struct Template<'s> {
  text: &'s str,
  stops: Vec<Stop<'s>>,
}

Although there’s a few different ways I can use such a template, the most convenient one looks something like this:

template!("templates/table-of-contents.html", out)?.feed(
  out,
  |label, out| {
    if label == "content" {
      write!(...);
      Ok(true) // Keep iterating!
    } else {
      Ok(false) // We're done (for now)
    }
  },
)?;

Since a TemplateRenderer is just a struct (that doesn’t allocate at all, mind you), I’m free to keep partially filled templates around until more djot parsing events get processed, without having to keep the partially-filled inputs in memory.

This theme of minimizing allocations when possible is something I’ve been trying to take to heart (even more in the period since). Both djot and LaTeX parsing is done using pulldown parsers (via jotdown and pulldown_latex respectively). That is, my code generator consumes streams of events instead of constructing an in-memory AST.

◇ LaTeX

Most websites I’ve come across seem to use either MathJax or KaTeX for LaTeX rendering. Shipping JavaScript would not be acceptable for this website, therefore MathJax was out of the equation (since as far as I understand, it operates on the client side only). I think KaTeX can be used to pre-render LaTeX blocks on the server (although the sites I’ve seen using it seemed not to do that for some reason). I don’t particularly remember why I didn’t go with it, although I guess the fact it runs on NodeJS would make usage from rust a bit painful. Oh well, I have working math, so that’s what matters!

◇ Gemini

Another cool benefit of using Djot is being able to define links separately from their usage:

Hello there, check out [my link][cool-link]!

[cool-link]: https://www.youtube.com/watch?v=dQw4w9WgXcQ

While cool in and of itself, this means I should (in the future) have an easier time generating gemtext files for the gemini protocol. I won’t go into detail here, as I don’t currently have such a generator working, but gemtext doesn’t support inline links (only on standalone lines), therefore link definition can be reused to have full control over the placement of such links!

◇ Metadata

I don’t think there’s any consensus (nor any built-in way) on how to include document metadata in Djot documents. I do it through a combination of blocks:

• The description of each article gets read from description blocks. Said description can later be displayed in places like pages listing various articles. Here’s how it looks:

  { role=description }
  :::
  According to all known laws of aviation, there is no way a bee should be able to fly. Its wings are too small to get its fat little body off the ground.
  :::
  

• Other metadata can be included through config blocks. There’s no required fields as of now, and some fields are implied by other fields (i.e. hidden implies sitemap_exclude). Moreover, not all metadata is stored in the file itself. Properties like the last_changed date are taken directly from Git!

  { role=config }
  ``` =toml
  hidden = ...
  created_at = ...
  
  sitemap_exclude = ...
  sitemap_priority = ...
  sitemap_changefreq = ...
  ```