Overall, my interest in digital gardens is I’m trying to stick to “what goes in the frame” than “how is the frame built”. Of course, the whole octothorpe idea is very, very much a frame idea. With that in mind, and with the world benefitting from excellent frame-makers like Dorian, my hunch is that I want an in-the-middle approach like so:
- Leave the website making to the things that make websites – Jekyll, Hugo, Next.js, whatever
- It’s ok for people to use their website-makers to make connections and meaning on their website in their usual way
- Use the RDF layer to do all the mapping / relating / remaking
- Any RDF and linked-data patterns should be able to read the cliff-notes version of this meaning and these connections (ie a Jekyll plugin that can convert tags / layouts to metadata)
- I think the canonical urls for a markdown-based SSG should be raw markdown files with rich frontmatter
- Octothorpes is a service that doesn’t care how your site is made, and expects to look at markdown files like that
- Lightweight plugins / converters maintined within the ecosystems of website-makers take care of going from Their Way of Doing Things to producing these canonical markdown files
- How much metadata goes into a human-readable public url is decided within the website-making step
- Octothorpes as a service a human would use does the following:
- parses and associates the meaning of the metadata on canonical urls with the content (markdown) within an namespace
- generates the relevant JSON-LD for that namespace
- coordinates / distributes resources like the plugins that a SSG would use to hook into the Octothorpoes ecostytem
- provides JS interfaces for the core features of the Octothorpes ecosystem to plunk in on sites that don’t use / have access to the above plugins ^. Eg:
- simple D3-like graph visualization of related content
- in-line activation of “octothorped” terms
- provides an infinite and growing set of visualizations, connections, remixes, etc from it’s galaxy of linked data… lalaal whatever this is the “future is bright / open source everything” part of the roadmap
- This step is where you would generate actual webpages from pure RDF / OWL / JSON-LD whathave you. This is fine, but I don’t think we should start there.
So this represents a pretty big departure from Dorian’s project. His swiss-army knife is super cool and interesting, but too unwieldy to carry in your pocket everywhere
I’m lookin at this stuff. Ecosystem seems healthy and well maintained.
We wrote version 1 in our heads, so why not make a spec for Version 2 before we actually write it in code
Octothorpes is a lightweight protocol for creating bidirectional links and event streams between documents, regardless of whether the documents are accessible via local or networked protocols. The octothorpe ecosystem consists of:
- yaml frontmatter
- an octothorpes parser
- an octothorpes server
Write documents in plaintext or markdown, describe them with basic YAML frontmatter. Run an octothorpes parser to create meaningful records that describe the documents and their relationships to other records.
A Parser runs in the same environment where you access the documents. For example, if you were writing documents in markdown files on your own machine, you would use the Octothorpes CLI. If you are writing them in Wordpress on a public blog, you would use an embedded script or Wordpress plugin.
An Octothorpes parser creates descriptive RDF records for each of your documents. These records can contain the full content of your documents, or simply a reference to a canonical source of a document’s content. Parsers deal with the following entities:
- Document records
- Octothorpe Terms (also known simply as
- User terms
Connect your parser to an octothorpe server to relate your parsed documents to other documents and terms. A
server reads the RDF created by parsers and provides an API for interacting with that information. Octothorpe servers respond to requests for all of the above entities and handle the following Events
- All ActivityPub actions
Parsing a document creates a descriptive record of a document that is treated as a permanent ID for that document in the Octothorpes ecosystem.
todo: document spec. I think docs should only require title, alias, terms, mode (r,w,x), and content (reference or canonical) but feels like more thinking is required.
Canonical document records
Optionally, the content of a document can be stored in the document record and treated as the canonical version. Separate files or URLS can be created from a canonical document record via Events, according to access rights a Server has to the environment in which those files exist. Setting a document record’s mode to
read-write requires converting it to a
CDRs could also be used when moving a set of documents to a new environment, preventing accidental editing of a document, or, conversely, if your preferred method of editing a document is with a (currently nonexistent) document record editor application.
Backlinks are bidirectional links between documents. Since Octothorpes uses RDF descriptions of your documents, these can be hyperlinks but don’t have to be. A backlink is simply a bidirectional relationship between any two documents the Octothorpes Server can identify. An octothorpes server includes backlink relationship information with any request for a document, and can respond to direct requests for backlink nodes.
todo: resolve backlink concept with activitypub maybe a good ref here?
Whereas backlinks describe a relationship between documents, Octothorpe Terms – or simply
octothorpes – describe a relationship between a document and a universal term. A document that is octothorped with the term
#octothorpe has a potential relationship to every other accessible document with the same octothorpe.
Browsing and following octothorpes
Octothorpe servers provide an API for all the terms and documents they know about. If this API is made public, it can be subscribed to or manually interacted with via ActivityStreams / ActivityPub protocols, or a
Example: Nik subscribes a private Octothorpes server (Server A) and subscribes to the popular public server octothorp.es. (Server B). Nim only subscribes to Server B, but When Nik issues a request for the octothorpe
#wombatshe sees results from Servers A and B. Nim will only see results from Server B.
An arbitrary number of terms can be associated with a document record. These can be as simple as plaintext tags or a full schema such as SKOS.
Sync is used to copy content between environments, according to the access rights of those environments.
Assuming the user has appropriate rights and access in both the environment where the
sync to and the
Parser that issues the request,the requested
server will respond with the canonical content and all terms for the requested
parser which issued the
sync request then creates an associated
document record . Environment variables or request params can be used to set whether that
document record uses the original as its canonical reference, creates a new file to reference, or creates a new
CDR backlinked to the original
mode is set to
read-write a sync request can be sent with an
overwrite flag, which will update the
document record with the canonical content of a separate
transform is a read-only version of
sync that can map
document record attributes to an arbitrary set of outputs according to schema definitions provided to the
parser in the form of JSON / JSON-LD. This is mainly a convenience function for
parsers, as the response from the
server will be the same as a
sync request, but upon success will trigger further work by the
parser that issued the request, according to env variables, request params, and schema definitions.
Example 1: Nim writes documents in Obsidian and publishes them on a Jekyll site. Both allow backlinking via alias but use different terms to define the alias. He sets up a simple schema definition that converts the
aliasterm to a
titleterm. He then uses the Octothorpes CLI to
transformdocuments within his working directory using the
obsidian-jekyllschema, outputting them as markdown files in his specified Jekyll directory. Example 2: Retweet the web. Nik reads an article he likes on a blog that provides public
document recordsfor each of its articles. Using a bookmarklet authenticated to his private
server, he can send a
transformrequest to his server which will convert the
document recordof the blog article he’s reading into a document format that his own website uses, creating a
backlinkto the original
document recordin the process.
feed request will create an rss/xml/whatever feed based on request parameters or
server defaults when sent.
Example: Nik and Nim create a shared, private
serverthat they both
synctheir notes to. They don’t feel like creating a website, but they want to share what they’re working on. So they set a public endpoint for
feed?authors=Nik-nim&format=rss-rdfthat allows anyone to subscribe via RSS. Of course, the feed includes well-formed
document recordsby default, so anyone running their own
serverlocally can easily
transformthat feed into any format they want.