A decent week hacking on personal software and ramping up the writing process for another dissertation chapter.
I’m experimenting with a few changes to Rheo to do with the performance issues in large rookeries that I talk about below.
The number of source files in waterline more than doubled this week, as I ported into it all of my applications from the 2025–26 season, as well as the majority of my annotated books and papers from the past few years. Since I moved resolutely to Linux and away from DEVONthink, these have been sitting in a folder in my Dropbox titled for_dt without any real systematization. Using @rookery/bibtex, I now have a mapping of every meaningful citation in my Zotero vault to an idea in waterline, and in turn can reference local documents and notebooks (PDFs with handwritten notes generated on a reMarkable) from that citational idea. This is a much smoother way of referencing texts within my writing environment, as the bibtex key essentially does double duty as the way I can get a well-formatted citation to the text, e.g. @knuthComputerProgrammingArt1992[p.2], and as a way to reference a page that links to the original text (if I have it) and the notes about it, e.g. @idea:knuthComputerProgrammingArt1992.
Beyond filling out my main rookery, I also vibe-coded a remarks tool to bring content from my reMarkable into waterline in a well-structured way. I’ve started writing a blog post about this, so I won’t get into the details: but I’m pretty happy with how it’s all working! It’s a rite of passage in the note-taking world to develop your own idiosyncratic system for note-taking—just as it’s a rite of passage in the blogging world to develop your own idiosyncratic system for blogging (rookery)—and I’m well on my way with my collection of Linux machines.11 I have a Framework Desktop and a Framework laptop, plus two reMarkables which run a Linux distribution called reMarkable OS, which you can SSH into and hack on.
I rewrote part of my dissertation’s introduction, and also started properly writing the chapter on Rheo, rookery, and the computerization of knowledge. For this, I’m returning to a collection of essays by Donald Knuth and some literature mapping the broader historical context.
I spent a significant number of cycles on performance diagnosis of waterline (my mainline rookery), which is now 611 Typst files and 1725 pages. Part of the compilation cost is due to how my current prototype makes use of the query function in windows to transclude content from other pages. When the layout in one context depends self-referentially on content that is part of the same context, Typst resolves the dynamic nature of this layout via an introspection loop. This loop bails out completely after five iterations, resulting in an incomplete Typst build. A rookery that makes use of all alpha packages currently needs all five to compile.
Some of this is to do with Rheo, which needs two iterations to stabilize a compilation. The exact source of the other three iterations is something I’m still working out, but it seems to come largely from @rookery/search. This makes sense, as search needs to reference and compress all ideas to make a full-text search panel available.
An obvious solution would be to move indexing and the search that it enables to a backend server, so that it isn’t necessary during the frontend’s compilation: but this would undermine a lot of rookery’s value-add as a Zettelkasten-style framework in pure Typst, as it would then also become a full-stack framework of sorts.11 There is an interesting question this thought surfaces about whether Typst could work well as a language in which backend servers are written; but interesting though it is, this is not the design space in which rookery wants to play. Instead I have decided to accept the cost of this up-front compilation more or less as it is, and spend time optimizing the incremental compilation of a rookery. That is, once you have built a large rookery once, compiling it again with a set of small changes in a development workflow should ideally be a sub-second operation. Rheo is well-positioned to help with this optimization frontier, as through it Typst files are already split out and loosely organized by folder structures. Because Rheo allows relative linking across source files, however, it isn’t as easy as simply tracking which files have changed and mapping that to a similarly small part of the build context to recompile.
I haven’t shipped any significant improvements yet—my 1725-page rookery takes around 20 seconds to cold start, and then around 10 seconds to recompile—but I am actively profiling both Rheo and rookery now, and have some ideas about how I might improve compile times as my rookeries grow and the recompilation time becomes more prohibitive.
With the rest of my rookery cycles, I gave my blog and weeknotes new skins and functionality. I shipped contents-panel, a Rheo package that provides a dynamic contents panel with progress bars, like the one you now see on this site on desktop. This package was distinctly inspired by (the less euphemistically inclined might say ‘copied from’) Anil Madhavapeddy’s site, as I really like the UX.
This led me to spend some time tinkering with the footnotes and citations in ideas to see whether I could produce the same style of horizontal footnotes as on Anil’s site, an experiment that ended up consuming the better part of a day. While it’s easy to get this style of footnotes working for any particular post, it took a bit of experimentation to settle on a sufficiently elegant way to encode it as a ‘horizontal display mode’ for footnotes and citations in rookery more generally, as an idea has multiple forms of appearance (a hatching context, a standalone page, a preview in a window or search panel) that all need to be accounted for. It’s now as simple as follows in the template:
#show: rookery.with(
footnotes: "horizontal",
display-right-gutter: true,
)While I originally had both footnotes and citations separately modifiable as "horizontal" or not, in the end I decided to only toggle on footnotes. This is because Typst allows bibliography styles such as "chicago-notes", which already displays inline citations as footnotes. Therefore you can effectively make footnotes and citations horizontal (as on Anil’s site) by choosing a citation style that puts references into footnotes. The display-right-gutter parameter is separate, for now, as it essentially tells rookery to spread content only two-thirds of the way on full-screen widths, leaving the remaining third for footnotes and/or the contents-panel.
Alongside this horizontal mode, I added some touch-ups to rookery to make it more mobile-friendly, such as truncating long idea hats with ... when the screen width doesn’t permit their full display. All of this work is making me think that rookery is as much a design system as it is a particular framework for Typst/Rheo. The bordering and hat defaults for ideas are what allow them to collapse to a cutoff display in windows, for example, which in turn enables them to be composited elegantly in a pinboard or slipshow. Moreover, tags are the metadata concept that makes windows, search, and other forms of filter and selection possible.