Slow and Steady

It's been months since I managed to write here. It's hard to remember all that's been going on but I have been finding some time for collards hacking again. There have been lots of collards improvements since my last post in February. The largest of which is probably default templates and support for incremental builds. There are other small goodies like support for custom markdown extensions, lots of bugfixes, and more polish to the command-line tools.

Ever since a co-worker mentioned I should have my own web radio station I've had an urge to spin up a "radio" subdomain. Having somewhere to write about my constant music exploration is very appealing. Generating music posts on a subdomain with collards had some pain points though which motivated me to hack.

Most of the pain came from deciding whether to reuse existing content types and collections or create new ones. It should be pretty easy to create custom post types: subclass post, define a custom render method, and add a type: my-subclass attribute to your yaml header. I was already doing this for slide decks made with remark and followed a similar approach for a "radio play" type.

It was less straightforward to create new collections. Largely because existing collections were tightly coupled to both: 1) the kind of content they contain, and 2) the way that they expect to order content chronologically and cross-link. In my experience, writing a static site generator is mostly straightforward but coming up with a good API for collections is one of the tricky parts. Collards had two collection rewrites I remember, both striving to make the collection support more flexible.

The first time I refactored them to make it possible to opt out of collections or control their URL generation by representing them in the filesystem like other content. My first attempt failed because I forgot that collections couldn't be generated during the build step like "normal content". Since they might include other content that isn't yet loaded, you have to build them after everything else is loaded. Thinking of static site generators as compilers from markdown files to HTML is a nice perspective, but you have to remember that as soon as collections come into play you're effectively building a two phase compiler!

The second refactor is the one I just completed to support the radio subdomain. I knew that I wanted a "playlist" collection type for music content and was surprised by how much code I needed as I tried to create it. The new code isn't perfect but it's less coupled and easier to extend.

A lot of the coupling was done to just get my site off the ground initially. Engineers often fall into the habit of building for future use cases that can be pretty speculative. I was trying to follow "YAGNI". Unfortunately, that meant there was a lot of implicit behavior both during the build step as well as during rendering because the only content type I had to begin with was posts. All the helpers for cross-linking and sorting chronologically expected posts.

Now that the refactoring is done, making a custom collection type is much simpler. It requires subclassing collection, implementing a populate method that can add whatever content is relevant, and defining a render method that serves as your template. A chrono-sort method to enforce ordering is optional. Hopefully now that the dust has settled, I'll get into a groove of writing more. Cheers.