# Means, Ends, Friends -- ## Or, "Didn't he give this talk last year?" _[talk source](https://git.sr.ht/~kingcons/kingcons.io/tree/main/item/talks/town-con-2025.md?view-source)_ --- ### Who are you? [kingcons]: https://kingcons.io .headshot[] Meatspace: `brit` Cyberspace: [~kingcons][kingcons] -- * 2011: Met Vil at my first job out of college * 2015: *Technically* joined town? * 2023: Started hanging out in chat more -- But you may not know me! I am awkward about community. I don't even call myself a lisper and I've been doing that 17 years or so. 🤷 --- [collards]: https://collards.kingcons.io/ [collards-repo]: https://git.sr.ht/~kingcons/collards ### This talk concerns... [readable]: https://blog.kingcons.io/posts/research-goals.html * A [static site generator][collards-repo] called `collards` built in Common Lisp * ["Readable" Code][readable]: a weird, nebulous idea * What I want from programs and computers * How our relationships with computers change --- count: false ### This talk concerns... Disclaimer: I struggle not to give philosophy talks. Apologies if we wander. --- ## Philosophy / Preamble Time for a Huxley quote. --- ## Philosophy / Preamble > We are living now, not in the delicious intoxication induced by the early successes of science, but in a rather grisly morning-after, when it has become apparent that what triumphant science has done hitherto is to improve the means for achieving unimproved or actually deteriorated ends. --- count: false ## Philosophy / Preamble > We are living now, not in the delicious intoxication induced by the early successes of science, but in a rather grisly morning-after, when it has become apparent that what triumphant science has done hitherto is to improve the means for achieving unimproved or actually deteriorated ends. We can come back to this but I find the "Why" of things really important. This quote has stuck with me for 20 years now. It has rarely been more central in my mind than during the horrifying explosion of AI in recent years. I care a lot about _intentionality_. --- ## Philosophy / Preamble I will also be slight obnoxious here and shill for a book I haven't read but that feels spiritually aligned with the kind of conversations we're having at Town Con and in Tilde Town in general. Promise I'll read it before next year. .seeing[] --- ## Philosophy / Preamble Bret Victor (fuck Stallman) is doing some of the best thinking I've seen about what it means for people to be truly empowered by computation and to have that reach a wide audience: -- > Today’s computers and apps are products, created by professional elites > for consumers. To use a computer means to constrain one’s work and thought to the > features of these mass-produced “tiny worlds”. This is utterly unlike real literacy, which > is an ability that we teach to every person, empowering them to create their own writing > to express any possible idea without constraint. There exists no corresponding form of > computing: an ability which could be taught to every person, empowering them to create > their own computing environments to express any possible idea computationally. --- ## Philosophy / Preamble I also said in my talk last year that "I am always thinking of a Milosz quote". There is, of course, a Milosz quote for [collards][collards] (the code) and it is this: > I have always aspired to a more spacious form > that would be free from the claims of poetry or prose > and would let us understand each other without exposing > the author or reader to sublime agonies. - Czeslaw Milosz, _Ars Poetica_ The way these docs are approached is a tiny, _tiny_ step towards software that can be experienced in what I've been calling a more "inside out" way. -- One other might be: ``` Where does humility come from? From sitting down and put­ ting little signs on paper with the hope of expressing some­ thing. [...] Those of the past are caught in the manners and style of their period; those of today move with difficulty in a transparent jam that is slowly coagulating. ``` --- ## What do I want from a SSG? I want to: * Be able to convert a git repo of Markdown to a folder of HTML + CSS * That folder should be trivially syncable to a remote host * I want to be able to link between content without thinking about URLs * I want live preview so I can look at things locally without deploying * I want dynamic collections (tags, chronological, etc) * I want it to be "pretty simple" to make new content types * I want it to be possible to create totally custom pages ** Technically, without dropping to HTML/JS, I'm stubborn --- ## Collards [town-con]: https://kingcons.io/talks/town-con.html#1 Tried to give a talk [last year][town-con], but it wound up all over the place. I was also kind of introducing myself to town. Plus collards was mostly sketched out but I think I got the site "building" during the conference and also there was zero styling or anything. Not much functionality. --- count: false ### Collards: What's new? [town-con]: https://kingcons.io/talks/town-con.html#1 A lot has changed since last year! In many ways, last year's talk was about why I wanted to make (another) SSG and where I find the energy and drive to write software. Hint hint: Community, Control, Creativity --- count:false ### Collards: What's new? I don't think I've ever written a piece of software I thought was "good" but Collards has a lot of qualities I like. I'll take it. Also, I like [my website][kingcons] now! 🎉 **Note:** My website (and these slides) are constructed entirely with collards, rsync'd to my server by collards for static hosting. --- count: false ### Collards: What's new? This year's talk will look more at collards in action but also more at the code, some maybe interesting lessons from development, thoughts on readability. I don't _think_ there are any other users yet. But who knows? Maybe some lisper found it. --- count: false ### Collards: What's new? [news]: https://git.sr.ht/~kingcons/collards/tree/main/item/NEWS.md [music-lib]: https://radio.kingcons.io/library.html Last year: 0.1, "can turn markdown into HTML" This year: 0.7.2, "lkjhasdlofuqlkneclizuh all of the things" [NEWS][news] tells the story but: * New subcommands: `serve` (i.e. live preview), `deploy`, `help` * **LOTS** more [docs][collards] * Subdomain support * Incremental builds * Default templates * Wikilinks across subdomains, content types, etc * [Custom pages / more fun content][music-lib] (maybe come back to this?) --- count: false ### Collards: What now? We're in a better place now. A live demo _might_ be interesting? Save for end. (i.e. like run plain `collards`, then nuke the build, preview config and repo layout, run serve) -- ... I regret I don't have binaries I can provide. If you want, you're welcome to clone & run make, ask me questions, etc. Intended use is building stuff locally and then running `collards deploy` to rsync it to a server your SSH agent can talk to. You may just want to write the HTML + CSS yourself. That's rad! --- ## Deep Dive So let's talk some about the architecture of this thing and the little abstractions it provides. --- ### Deep Dive: Architecture I care a lot about "readability". I also hate talking about "readability". What do we mean? --- ### Deep Dive: Architecture Readability is 100% dependent on the context of your reader. Thus, no single linear codebase traversal makes sense. -- For purposes of this talk, do I start by talking about the build process for a site? Or do I talk through the various layers of the collards app itself? --- ### Deep Dive: Architecture I won't go over the models, templates, or CLI tools in this talk. I would like to talk about the "Core" module / main abstractions. Though writing an SSG may seem a bit prosaic. -- The foundational pieces are: * **Site**: Noteworthy for holding the config data and the content registry. * **Content**: A base expectation that anything we render HTML for has a source file it was loaded from, a title, and a slug ** The more interesting piece here is the Content protocol: get-type, parse, and render * **Registry**: Basically a big hash table from "Content IDs" like `post:my-first-post` to content instances with some querying tools bolted on. --- ### Deep Dive: Collections Every time I've worked on an SSG, maybe half of the headaches are with Collections. -- It is reasonable to think of an SSG as a compiler from Markdown to HTML. -- But when you start having automatic pages generated from other content, you have a two-pass compiler and distinct build phases. You have to be careful about how they interact. -- I am pleased for some reason that collections didn't wind up in the "Core", they're just another model that has a `populate` method and runs in a separate build step. -- They also introduce some complications for linking because you probably want to support previous / next between pages and posts, etc. --- ### Deep Dive: Docs [cl-6502]: https://redlinernotes.com/docs/cl-6502.pdf [pax]: https://melisgl.github.io/mgl-pax-world/pax-manual.html I've been experimenting with readable programs for a while. [This][cl-6502] is my last literate program. It is a 6502 CPU emulator also written in lisp, rendered as a PDF. It actually sold a few copies on Lulu! -- The docs for collards may be of interest. I used a lisp library called [PAX][pax]. -- There have been a lot of experiments with "Literate Programming" going back to Knuth where you just write a book, embedding code snippets as you go through it with some instruction on how to stitch the code together at build time. -- PAX instead flips that on its head and has you embed docs in the code with some structure for stitching a manual together from it at build time. --- ### Deep Dive: Docs [journal]: https://git.sr.ht/~kingcons/collards/tree/main/item/JOURNAL.md I've had fun using it. I don't know if I advocate for "Docs Driven Development". I _do_ advocate for a [JOURNAL][journal] file. -- As mentioned by Nate, I think, and others the notion that code can be and should be a deep, intentional form of communication is important to me. -- One of the first things I learned about programming was: `Thus, programs should be written for people to read and only incidentally for machines to execute.` --- ## My Changing Relationship with Tech When I think about the programs I love, they have some consistent values: -- * They let me organize my data the way that makes sense to me. * They **DO NOT** fuck with my data or my access to my data. -- * They let me share myself, be seen, by people I care about. They are tools of communication and expression, not commerce or production. -- * They are either friendly to introspection and tweaking (emacs), or tweaking is of little value (signal). --- ## My Changing Relationship with Tech When I was younger, computers were an escape, a sort of demilitarized zone where I could experiment without the close observation I otherwise often felt under. But nowadays, the peace I find is in escaping to parks, watching my dog run, grabbing a cocktail in some quiet neighborhood bar, new music in my headphones. --- ## Conclusions [dynamicland]: https://dynamicland.org/ [gtoolkit]: https://gtoolkit.com/ * Static Site Generators are fun. * We don't really know how to make "inside out" software yet. * Things like [Dynamicland][dynamicland] and [Glamorous Toolkit][gtoolkit] point in interesting directions. * The important thing about software is how it connects us to each other and ourselves. * Thanks for having me. (Maybe showoff radio.kingcons.io here if people want?) --- ## Bonus slide Live demo if desired... Hypothetical town user `.collards` config? ``` (:author "Your name" :domain "tilde.town" :server (:host "your_user@tilde.town" :webroot "/home/your_homedir/public_html/") :repo-url "https://git.sr.ht/~your_user/your_site_git_repo" :ignored ("archives" "drafts" "scripts") :title "A beautiful new website") ```