Local Yarn: Source Code Notes

These are my notes about the internals of the Local Yarn source code. In other words, a personal reference, rather than a tutorial.

You’ll get the most out of these notes if you have read Pollen: the book is a program, and worked through the tutorials there by hand.

Note that these pages are heavily interlinked with the central Racket documentation at docs.racket-lang.org, which are written and maintained by others.

Some links from those pages will not work unless you open this page in its own tab.

Here’s a rough diagram showing how the .rkt modules in this project relate to each other, and to the Pollen source documents. This is the least complex system I could devise that would A) implement everything I want in my Design Goals, B) cleanly separate dependencies for print and web output, and C) organize an ever-growing collection of hundreds of individual notes and articles without noticable loss of speed.

The modules are arranged vertically: those on the upper rows provide bindings which are used by those on the lower rows. The bottom row are the .poly.pm files that make up articles and series.

Individual articles, while they are being rendered to HTML pages, save copies of their metadata and HTML to the SQLite cache. This is done by calling parse-and-cache-article! from within their template.

Any pages that gather content from multiple articles, such as Series pages and the RSS feed, pull this content directly from the SQLite cache. This is much faster than trawling through Pollen’s cached metas of every article looking for matching articles.