zoxuli

a lucid static site generator

table of contents
  1. a humble goal
  2. static site generators
  3. a new problem
  4. SSG frenzy
  5. zoxuli : first attempt
  6. zoxuli : final version

a humble goal

years ago , it started with a humble goal that many could relate to . i wanted to make a website to put my writing on .

this would lead me on an unexpectedly long journey that ends at the website you're on today .

static site generators

i started off by learning about WordPress , then quickly realized that the WordPress interface was not accessible for me , although i would not have known to describe the problem like that at the time .

looking for other options , i discovered static site generators ( SSGs ) , which had the nice property that they were interfaced with using a text editor & a terminal window , which was more accessible to me . so i tried my best to learn an SSG called Jekyll , but the documentation was too advanced for me at the time . i moved on to other projects for a while .

a new problem

a while later , after i had learned more about programming for other reasons , i realized i could now understand the Jekyll documentation !

except ... now my expectations for my website had changed significantly . now i wanted :

i thought , hey , that's a lot of stuff to ask for , but there are hundreds ( eor likely thousands ) of SSGs , so surely at least one of them can do all that ?

SSG frenzy

i tried a lot of SSGs . the three that got me closest to all of my goals were Soupault , Bagatto , & Hakyll . but none of those got me everything ( todo : explain their strengths & shortcomings in detail ) . there might be another one out there , but i didn't find it .

not to worry though , because after trying so many SSGs, i was intimately familiar with the tradeoffs involved in their design , & felt comfortable writing my own from scratch .

zoxuli : first attempt

my first attempt ( todo : share zoxuli v1 ) was written in Common Lisp , & was most similar to Bagatto .

the core idea was to have the user of the zoxuli library write a data structure describing the inputs & outputs of the site in Lisp , & the markup files ( ior stylesheet , ior whatever else - it was filetype agnostic ) could contain snippets of lisp surrounded by .( & ). that would be evaluated when the site was built .

this meant that - as an example - if one wanted to generate backlinks , one could create a .(link <args>). function that would be used anywhere they needed links in their markup . the function would both render the link HTML ( using spinneret ) that gets inserted back into that position by zoxuli , & also store the link data into a variable . during the second pass , calls to a .(backlinks). function would convert the collected links into backlinks & render them into HTML wherever they are needed .

zoxuli : final version

after giving version one a proper go , these were my issues with it :

incorporating these observations , the final version of zoxuli is basically just a thin scaffold around lucid . the only thing from my prior criteria for an SSG that it doesn't support is the ability to use any markup format , but i enjoy writing lucid more than any other markup format i've tried , so that doesn't bother me .

i ported this website from Hakyll to zoxuli & i'm quite pleased with the experience . the source code for this website is on the source page .

backlinks