site rewrite 2024 edition

previously this site was built with remix, serving data stored in sqlite and content was authored in logseq and pushed up to the site via a custom logseq extension. this was fun to make, and worked well enough but logseq isn’t a very good place to edit documents for the web. i wanted my content back on the file system in a proper format, and there was nothing dynamic preventing me from using a static site generator.

so now it’s composed of astro, keystatic and markdoc.

astro

i started with 11ty but didn’t really like the way ‘nunjucks’ rolled off the tongue, and found myself messing around trying to get their jsx templates working for a bit before realizing astro worked that way by default, and had good typescript support for content, too. it’s the dream static site builder as far as i’m concerned.one thing missing is being able to write type safe links, i see that missing in other frameworks too and wonder why it’s not more common

keystatic

wow, keystatic is totally wonderful. open source cms that uses github for storage. i first tried pagescms and then tina before coming across keystatic, and there are some things that keystatic gets right that i really enjoy:

  • good typescript types are offered for the schema definition where you define what kind of content is managed in keystatic
  • super nice editor view, particularly with the entryLayout option
  • good image support in the editor, and it stores them in per-post directories – it doesn’t have the global wordpress-esque ‘media library’
  • first class support for self hosting, deploys easily enough to cloudflarewell, it wasn’t working right on cloudflare pages until i downgraded the @astrojs/cloudflare package to version 9.2.1
  • diving into the code is a pleasant experience

overall it’s interesting that it’s a full wysiwyg-ish editor. even though it serializes and persists documents to plain text, it doesn’t let you toggle something to see the source. this was a surprise to me but something i think is good: i don’t get distracted with the markup generated and i don’t have a crutch to do things in code that should be done through the ui.

i think it’s a pretty fresh project, but feels super solid when using it so i’m really grateful it’s open source and i can try it out and tweak it.

screenshot showing the edit view of this document in keystatic's UI

keystatic’s UI

markdoc

i want my notes to be durable and portable for the next time i rewrite this site, and markdown is the obvious choice but you quickly get into the world of learning all the differences between what people think markdown is. ‘markdown flavours’, they make me sick. and if you want anything fun or cool that’s outside of that you might run into the unpleasant prospect of describing your own flavour with stuff like remark, rehype and it’s ilk, and this seems like a sure way to put an expiration date on your work. another popular way of taking this on is mdx, which is a programming language.i think people often misunderstand the security implications this brings as much as i like jsx, writing documents in a PL doesn’t sit right with me.

so when i came across markdoc’s description my eyes lit up:

By design, Markdoc is not a full-blown templating language and does not allow mixing arbitrary code and content. It is, however, a fully declarative format that is machine-readable from top to bottom: it parses to a data structure that can be traversed to support powerful static analysis, validation, and programmatic content transformation.

it’s markdown with support for custom components via a totally reasonable syntax! and nice tools for messing with the AST when you need to manipulate the content.e.g. to support these sidenotes

i had come across markdoc through keystatic, so it was convenient that they have a very cool way of integrating it with their editor. it’s all gui based, with a friendly api around customizing the editing experience.

overall, some really nice software that people make available for free. we’re living in the golden age of static websites.

© 2024 peter schilling