twtxt Developer Documentation Developer doumentation for twtxt (the project)

• Home
• Documentation
• Twt Subject Extension
• Multiline Extension
• Archive Feeds Extension
• Metadata Extension
• Multi User User-Agent Extension
• Hash Tag Extension
• Twt Hash Extension
• APIv1 Specification
• Tech Stack

At twtxt.net the Twt Subject was invented as an extension to the original Twtxt File Format Specification.

Purpose

Twts in their purest form provide only the mentions mechanism to reply to certain twtxt users. This works well in small, low traffic twtxt communities. However, if there are several ongoing discussions at the same time, a single mention may not be enough for consuming twxt users to clearly identify the exact conversation this twt is considered part of by its author. So, historically, twtxt users quickly started to provide more context in parentheses at the beginning of the twt right after any mentions – the so called subject.

The twt subject provides a mechanism to specify references in twt replies and thus group twts into entire conversations.

This early form has been superseded by a machine-readable and machine-writable format, for example:

(#2h35sba) @<nick1 url1> @<nick2 url2> Here's my response.

Format

The twt subject is the very first contents in parentheses right before, after, or in between any optional mentions in the twt text. The opening and closing parentheses are not part of the subject contents, but rather enclose it. Apart from mentions and whitespace, there must not be any other text preceding the subject or else the parenthesized text must be treated as regular text.

The Twt Hash of the first twt starting the conversation should be used in the twt subject. This machine-parsable version of subjects allows clients to easily group several twts to conversations automatically.

There must be exactly one twt hash in the subject. The syntax is one of these:

(#hash) here's text

(#hash) @<nick url> here's text

@<nick url> (#hash) here's text

@<nick url> (#hash) @<nick2 url2> here's text

Putting mentions before the hash is still supported but discouraged. You should stick to one of the first two forms.

A conversation uses a single twt hash in all the subjects throughout the whole discussion, namely the one from the twt starting the conversation. In order to branch off, the appropriate twt hash can be used in the following subjects to form complex conversation trees rather than just linear flows.

Clients may hide the subjects to use the available space more efficiently for contents.

Examples of replies referencing a twt with hash “abcdefg” (keep in mind these twts are on one physical line, but may be rendered in several ones depending on your font size and screen width):

(#abcdefg) @<joe https://example.com/twtxt.txt> @<kate https://example.org/twtxt.txt> Yes, I agree.

@<joe https://example.com/twtxt.txt> (#abcdefg) @<kate https://example.org/twtxt.txt> Hmm, are you sure? What if…

(#abcdefg) But what about…?

Changelog

• 2020-12-22: Initial version.
• 2022-11-25: Twt subjects are plain twt hashes now, instead of Hash Tags. This simplification reflects what’s currently used in the wild.