/ projects / zoxuli

zoxuli

1/5 in the series liberatory computing ∀ →

❡ 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 .

"making the website will be the simple part !" , i thought , once . lol .

❡ static site generators

this would lead me on a long journey that ends at the website you're on today . 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 were more accessible to me . so i tried my best to learn the SSG 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 :

• excellent accessibility
• post series with navigation
• tables of contents
• tags that work across multiple categories of pages
• backlinks
• footnotes
• breadcrumbs
• control over where & how the aforementioned elements appear
• syntax highlighting
• LaTeX
• semantic markup
• no javascript
• broken link checking
• simple & powerful extensibility in a comfortable language
• the ability to write pages in any markup format
• a fast development feedback loop

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 you wanted to generate backlinks , you could create a .(link <args>). function that would be used anywhere you needed links in your 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 you needed .

❡ zoxuli : final version

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

• i ended up using so many Lisp functions in the markup that i felt like i would've been better off just writing the markup in spinneret
• my implementation resulted in slower build times than i had hoped
• around that time , i realized i don't like programming in Lisp nearly as much as Haskell , especially after learning how to use ghcid properly
• i also discovered the lucid library for Haskell that i favored over spinneret for a few reasons

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 .