This site maintains the documentation for the Twtxt specification and its extensions, which are developed and maintained by the community.

What is Twtxt?

Twtxt is a minimalist, plain-text micro-blogging format that is simple to use and easy to understand.

The original Twtxt v1 specification, designed and developed by @buckket in ~2016, can be found at https://twtxt.readthedocs.org.

What follows is a revised specification that builds upon Twtxt v1, incorporating a minimal subset of the Extensions that have been developed over time.

How it works?

Twtxt operates via simple text files called “feeds,” each containing a user’s status updates. These files are typically served by web servers and made accessible through a URL (e.g., https://example.com/twtxt.txt).

File Format

A Twtxt feed contains one status update per line. Each line starts with an RFC3339 date-time string (with or without a UTC offset), followed by a TAB character (\t) that separates it from the actual text (it is recommended to append new statuses to the end of the file).

The file must be UTF-8 encoded and use LF (\n) as line separators.

A feed typically begins with metadata, which might include the user’s preferred nickname, an avatar, and an optional description. It is recommended to separate metadata from statuses by a blank line.

Mentions and Threads

Mentions in the text take one of two forms: @<source.nick source.url> or @<source.url>. These should be expanded by the client when rendering the Twts. The source.url helps discover new feeds and distinguish between users with the same nickname on the same domain. The source.url can be interpreted as a Twtxt URI.

Threads are represented using subjects, which are written in the format (<subject>) at the start of a Twt. For precise threading, content-based addressing identifies individual Twts in a feed. See the Twt Hash extension for more details.

Participation in a thread is simple: reply by copying the Twt Subject into a new Twt. A Twt Hash is a Blake2b hash, base32 encoded without padding, converted to all lowercase letters and shortened to the last 7 characters. The hash is calculated from the content <url>\n<timestamp>\n<text>.

For example:

$ printf '%s\n%s\n%s' \
  'https://example.com/twtxt.txt' '2024-09-29T13:30:00Z' 'Hello World!' \
  | b2sum -l 256 | awk '{ print $1 }' | xxd -r -p | base32 \
  | tr -d '=' | tr 'A-Z' 'a-z' | tail -c 8
ohmmloa

Example Feed

Below is an example of a Twtxt feed:

# nick        = example
# url         = https://example.com/twtxt.txt
# avatar      = https://example.com/avatar.png
# description = An example feed

2024-09-29T13:30:00Z   Hello World!
2024-09-29T13:40:00Z   (#ohmmloa) Is anyone alive? 🤔