On this page:
2.1 Design Goals
2.2 Names for things and how they fit together
2.2.1 Articles
2.2.2 Notes Notes vs. blog “comments”
2.2.3 Series Series vs. blog “categories”

2 Basic Notions

2.1 Design Goals

The design of The Local Yarn is guided by requirements that have evolved since I started the site in 1999. I enumerate them here because they explain why the code is necessarily more complicated than a typical blog:

2.2 Names for things and how they fit together

The Local Yarn is mostly comprised of articles (individual writings) which may contain notes (addenda by the author or others) and may also be grouped into series. These are similar to a typical blog’s posts, comments and categories, but there are important differences.

2.2.1 Articles

The article is the basic unit of content, like a typical blog post. In the web edition, each article has its own .html file; in print editions, an article may comprise either a chapter or a part of a chapter, depending on the content.

An article can start out very small — just a date and a few sentences. Supplying a title is optional. Later, it may grow in any of several directions: notes can be added, or a title, or cross-references to later articles; or it may be added to a series. Or it may just remain the way it started.

2.2.2 Notes

A note is a comment or addendum to an article using the note tag. It may be written by the same person who wrote the article, or submitted by a reader.

As shown above, a note appears at the bottom of the article to which it is attached, but it also appears in the blog and in the RSS feed as a separate piece of content, and is given the same visual weight as actual articles.

A note may optionally have a disposition which reflects a change in attitude towards its parent article. A disposition consists of a disposition mark such as an asterisk or dagger, and a past-tense verb. For example, an author may revisit an opinion piece written years earlier and add a note describing how their opinion has changed; the tag for this note might include #:disposition "* recanted" as an attribute. This would cause the * to be added to the article’s title, and the phrase “Now considered recanted” to be added to the margin, with a link to the note. Notes vs. blog “comments”

Typical blog comments serve as kind of a temporary discussion spot for a few days or weeks after a post is published. Commenting on an old post feels useless because the comment is only visible at the bottom of its parent post, and older posts are never “bumped” back into visibility.

By contrast, notes on The Local Yarn appear as self-contained writings at the top of the blog and RSS feed as soon as they are published. This “resurfaces” the original article to which they are attached. This extra visibility also makes them a good tool for the original author to fill out or update the article. In effect, with notes, each article potentially becomes its own miniature blog.

The flip side of this change is that what used to be the “comment section” is no longer allowed to function as a kind of per-article chat.

Typical Blog Comments


Local Yarn Notes

Rarely used after a post has aged


Commonly used on posts many years old

Visible only at the bottom of the parent post


Included in the main stream of posts and in the RSS feed alongside actual posts

Invites any and all feedback, from small compliments to lengthy rebuttals


Readers invited to treat their responses as submissions to a publication.

Usually used by readers


Usually used by the original author

Don’t affect the original post


May have properties (e.g. disposition) that change the status and presentation of the original post

Moderation (if done) is typically binary: approved or not


Moderation may take the form of edits and inline responses.

2.2.3 Series

A series is a grouping of articles into a particular order under a descriptive title. A series may present its own written content alongside the listing of its articles.

The page for a series can choose how to display its articles: chronologically, or in an arbitrary order. It can display articles only, or a mixed listing of articles and notes, like the blog. And it can choose to display articles in list form, or as excerpts, or in their entirety.

A series can specify nouns (noun phrases, really) to be applied to its articles. So, for example, a series of forceful opinion pieces might designate its articles as naked aspirations; the phrase “This is a naked aspiration, part of the series My Uncensored Thoughts” would appear prominently in the margins. Likewise, a time-ordered series of observations might call its articles “journal entries”.

It will be easy for any series to become a printed book, using the techniques I demonstrated in The Unbearable Lightness of Web Pages, and in Bookcover: Generating PDFs for book covers. Series vs. blog “categories”

Typical blogs are not very good at presenting content that may vary a lot in subject, length and style. The kind of writing I want to experiment with may change a lot from day to day, season to season, decade to decade. I wanted a single system that could organize extremely varied kinds of writings and present them in a thoughtful, coherent way, rather than starting a new blog every time I wanted to try writing a different kind of thing.

My solution to this was to enrich the idea of “categories”. Rather than being simply labels that you slap on blog posts, they would be titled collections with their own unique content and way of presenting articles and notes. In addition, they could pass down certain properties to the posts they contain, that can be used to give signals to the reader about what they are looking at.

Typical Blog Categories/Tags


Local Yarn Series

Every article needs to have one


Many or most articles won’t have one

Named with a single word


Named with a descriptive title

Has no content or properties of its own


Has its own written content, and properties such as nouns, ordering, etc.

Broad in scope, few in number


Narrow in scope, many in number

Selected to be relevant for use across the entire lifetime of the site


Selected without reference to future creative direction; may be closed after only a few articles