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 Hash Tag was invented as an extension to the original Twtxt File Format Specification.

DEPRECATION NOTICE

This specification is deprecated.

Twtxt files should contain plain hash tags, like #MySubject. They should not be linked to one particular search engine; it is up to the clients to do this.

The old contents of this specification are only provided for reference.

Purpose

Users might want to tag their twts with labels to make their contents detectable by other users who are searching for a certain topic. Those labels are called hash tags. They can be used to group several twts on a specific topic. Hash tags enable crossreferencing of twts, e.g. by their most prominent use in the Twt Subject.

Format

Inspired by twtxt mentions, which use the @<nick url> syntax, hash tags are in the form of #<tag url>. Tag and URL are separated by a single space character. Multiple whitespace characters might be used, but their use is discouraged.

Both tag and URL are mandatory and must not contain any whitespace. This extension does not specify a way to escape whitespace in the tag or URL parts. If the text between #< and > cannot exactly be split into two parts – tag and URL – the whole sequence must be treated as regular plain text.

Tags must only contain lower or upper case ASCII letters, numbers, underscores and minus signs. Other characters are not allowed. A valid tag conforms to the following regular expression: [a-zA-Z0-9_-]+.

The closing angled bracked (>) cannot be escaped in the URL, other than using its URL-escaped form %3E.

The URL must point to a resource which lists twts for the given tag.

Clients should render the hash symbol (#) right in front of the tag. Hence, the name “hash tag”. Given the hash tag #<foo https://example.com/tags/foo> in a twt a terminal client might show it as:

#foo (https://example.com/tags/foo)

A web UI might generate HTML like:

<a href="https://example.com/tags/foo">#foo</a>

Security Considerations

Clients supporting this extension should provide a way to show the full URL to the users in advance, so that users are able to see, where they would end up when following the URL. This way users can abort and decide against visiting a URL.

Clients may also provide a way to disable hash tag URL folding entirely and always render the URL next to the hash tag in full length.

Changelog

• 2020-12-16: Initial version.
• 2022-12-21: This specification has been deprecated.