Designing Notes

Here are some design ideas for extending my fork of Plerd to implement notes.

What are notes?

Notes are twitter-like short posts lacking markup or titles, but may have embedded tags. Structurally, these notes should be published marked up like Indieweb Notes.

Note tags are implemented as post tags and will be visible on the Archive view generated by Plerd.

Notes do not support markdown. Adding structure to notes seems antithetical to their purpose. Plerd::Posts already support markdown quite well.

Notes also do not support attribute tags, like posts. These are simple blobs of text.

The only formatting that will be respected are spaces and new lines, since the post will be wrapped in block element styled with white-space: pre.

URLs should also be replaced with HTML anchors. No URL shorteners are required since there is no limit on the size of notes.

The first line of a note may be treated specially. If the line contains a valid URL preceded by a “command” string, it should generate a citation. Commands are:

 ->       [The note is a reply to the document at the given URL]
 ^        [The note approves, supports, endoreses the content of the given URL]

The note is marked up using the h-entry microformat and is intended to be consumed as a web mention.

See the Example notes at the end of this document.

How are you going to make this a thing?

The user should create a new directory for note posts. The default will be:

Path::Class::File->new($config->source_directory, "notes");

Which is to say, a subdirectory off of the source directory.

The method Plerd::publish_all should scan the notes source directory for new notes. When a new note is detected, it is parsed for tags, which are recorded in a memory, just like posts.

Also like posts, notes are written back out to the original source file with a filename that begins with a Unix epoch timestamp (with microsecond resolution? Thinkie!).

The URI to a specific note should be something like:


Notes should have a phrase which should be the HTML anchor text. This phrase should consist of the first 5-7 words of the post. Some clever heuristic could be devised to create a pleasant phrase.

Example link to a note

The template code might look like:

Check out <a href="[% note.uri %]">[% note.title ]</a>

The rendered HTML might look like:

Check out <a href="http://bloghost/note-1593786477.html">Why I like cats</a>.

The attributes of the note object mirror a Post.

Example of rendered note

<div class="h-entry">
    <div class="e-content">Why I like cats?  Why wouldn't I? 
    <a href="http://bloghost/tags.html#tag-favorite_things">#favorite_things</a>

Not shown in this sample are the author attribution and other metainformation, as per the h-entry microformat.

When notes are published to HTML, tags are to be hyperlinked, in the same way posts are.

Notes Roll

Notes are collected into a view called Notes Roll, which is a reverse chronological view of published notes. At the bottom of this roll should be a link to the Notes Archive view.

Because notes are expected to grow without bound, only the most recent 25 notes will be shown. All notes should be shown in a list view like the Archive view.

Notes feed

The most recent notes should be available as a RSS feed.

The front page of the plerd should also so the latest notes in the sidebar.

Architectural considerations

Notes should be a subclass of Plerd::Model::Post and have a its own template.

NotesRoll is a model class with its own template.

NotesArchive is a model class with its own template.

NotesFeed is a model class with its own template.

Plerd::publish_all() needs to detect notes and republish affected views as needed.

Example note 1 (unicode, tags)

I hate Mondays. ☹️
#mondays #rainydays

Example note 2 (preserve spacing)

 Living like

Example note 3 (reply-to citation)

This garbage site is garbage.

Example note 4 (like citation)

Although it too is a garbage site, I rather prefer it to others.