Introduction

Scroll is an internet protocol for file-transfer served over port 5699. It is heavily influenced by the Gemini, Gopher, and Gopher+ protocols.

Scroll builds on Gemini and Gopher by adding some helpful features:

  • Each response includes metadata: author, publish date, modification date.
  • Clients can request documents in their preferred language(s), with a fallback to the server’s default if the requested language(s) are unavailable.
  • Metadata requests provide extra details about documents, like summaries and abstracts.

Core Values

The core values of scroll diverge from both Gemini and Gopher in important ways:

  • Approachability
  • Expressiveness
  • Simplicity, not minimalism
  • Document-centric, not text-centric or page-centric
  • User Autonomy and user control over presentation
  • Stability
  • Privacy
  • Streamable document format(s)

Goals

The Scroll protocol is intended to cultivate a particular Scroll ecosystem, or scrollspace, that is aligned with the following goals:

  • No ads and tracking
  • No scripting on pages (No JS, WASM, Flash, or Java)
  • No insecure markup features like iframes, cookies, user-agents
  • Simplicity for writers and developers
  • User-focused content - the writer provides the content, the user determines most of the styling
  • Offer simpler alternatives to HTML Semantic Markup and Open Graph Tags with a Markdown and AsciiDoc inspired markup language
  • Multi-media that doesn’t interfere with your reading or browsing experience
  • Document-oriented rather than page-oriented
  • Searchable and Indexable

Comparisons to Other Smallnet Protocols

Comparison: gemini:// vs. spartan:// vs. scroll:// vs. nex://

                             gemini       spartan           scroll                nex
                             ------       -------           ------                ---
naming scheme                space        sparta/greece     scrolls & libraries   cityscape & highways
transport                    TCP + TLS    TCP               TCP + TLS             TCP
request structure            full URL     hostname & path   full URL              path
request encoding             utf-8        us-ascii          utf-8                 utf-8
status codes                 18           4                 18                    0
document type                text/gemini  text/gemini       text/scroll           text/plain
input prompt                 1x status    "=:" prompt line  1x status             none

data upload                  limited      yes               limited               no
mimetypes                    yes          yes               yes                   no
virtual hosting              yes          yes               yes                   no
same-site redirects          yes          yes               yes                   no
cross-site redirects         yes          no                yes                   no
proxy requests               yes          no                yes                   no
"lang" response parameter    yes          no                yes                   no
lang request parameter       no           no                yes                   no
response metadata            heuristic    heuristic         yes                   heuristic
abstract/metadata requests   no           no                yes                   no

link relationships           heuristic    heuristic         yes                   heuristic
list nesting                 no           no                yes                   heuristic

What the Heck is a Protocol?

Web vs. Internet

The World Wide Web (WWW) is just one of many services that run on the Internet. While the terms Internet and Web are often used interchangeably, they refer to different things:

  • The Internet is the global network infrastructure that connects computers worldwide, allowing communication between two or more computers
  • The Web is a system of interlinked hypertext documents accessed via the HTTP/HTTPS protocol

Other Internet services include email (SMTP/IMAP/POP3), FTP, IRC, Gopher, and more recently, protocols like Gemini and Scroll. Each of these protocols serves different purposes and has different strengths.

Scroll, like Gemini and Gopher, is an Internet protocol - not a web protocol. This means:

  1. It operates independently from the Web and HTTP/HTTPS
  2. It has its own port (5699) rather than using ports 80/443
  3. It uses its own URL scheme (scroll://) to clearly separate it from web URLs
  4. It focuses on document transfer rather than web pages and applications
  5. It intentionally lacks many web features like cookies, JavaScript, and complex styling

While the Web has grown increasingly complex and commercialized, Scroll aims to provide a simpler, more focused protocol for sharing and accessing documents over the Internet. It exists alongside the Web rather than trying to replace it, serving as an alternative space for content that benefits from a more streamlined approach.

The key distinction is that Scroll is a protocol for transferring documents over the Internet infrastructure, not a subset or variant of the Web. This allows it to make different design choices that prioritize simplicity, privacy, and user control over the features and complexity that characterize the modern Web.

Internet Protocol

An Internet protocol is a standardized set of rules for how computers communicate over the internet. These protocols define:

  1. Message Format: How data should be structured when sent between computers
  2. Request/Response Rules: What kinds of messages can be sent and what responses are expected
  3. Port: Which numbered port the protocol uses (like 80 for HTTP or 5699 for Scroll)
  4. Transport: Whether it uses TCP, UDP, or other transport protocols
  5. State: Whether the protocol maintains state between messages or is stateless
  6. Error Handling: How to handle and communicate various types of failures

Protocols can serve different purposes:

  • Application Protocols (HTTP, SMTP, Gopher, Gemini, Scroll) define how specific applications communicate
  • Transport Protocols (TCP, UDP) handle reliable data delivery
  • Internet Protocol (IP) handles routing packets between networks, and identifying computers with IP addresses.
  • Link Layer Protocols (Ethernet, Wifi) manage direct computer-to-computer communication

Scroll is an application protocol that:

  • Uses TCP for reliable transport
  • Operates over TLS for security
  • Is stateless (each request stands alone)
  • Has a simple request/response format
  • Uses UTF-8 encoding for headers

By defining these rules clearly, protocols allow different software implementations to communicate reliably without needing to know the internal details of how each program works. This standardization is what makes the Internet possible as a network of different computers and programs working together.

File-Transfer

File-transfer protocols serve as standardized ways to request and receive files over the internet. These protocols solve several important problems:

  1. Resource Location: They define how to identify and locate files through URLs or other addressing schemes
  2. Content Negotiation: They specify how clients and servers agree on what format to transfer content in
  3. Metadata Exchange: They determine what information about files should be shared before/during transfer
  4. Error Handling: They establish how to communicate and handle various failure scenarios
  5. Transfer Rules: They set expectations for how data should be transmitted and received

Different file-transfer protocols make different tradeoffs in solving these problems. For example:

  • HTTP emphasizes flexibility and features, supporting complex content negotiation and rich metadata
  • Gopher focuses on simplicity with its menu-based navigation and minimal metadata
  • Gemini strikes a balance with TLS security and basic content-type information
  • FTP separates control and data channels for more detailed transfer management

Scroll’s approach as a file-transfer protocol emphasizes:

  • Clear metadata for every response (author, dates)
  • Language negotiation as a first-class feature
  • Document-centric resource identification
  • Streaming-friendly response format
  • Ability to request metadata separately from content

The goal is to provide enough information and features to make document sharing effective while maintaining simplicity and avoiding the complexity trap that HTTP fell into. By focusing specifically on document transfer rather than trying to be a general-purpose application protocol, Scroll can make design choices that better serve its core use cases.

Hypertext

Hypertext is text that contains references (hyperlinks) to other texts, allowing readers to immediately access related documents. In file-transfer protocols, hypertext serves several crucial functions:

  1. Navigation: Links create paths through collections of documents, letting users move naturally between related resources
  2. Context: The text surrounding a link explains its relationship to the current document
  3. Discovery: Links help users find new resources they wouldn’t have known to search for
  4. Organization: Documents can be organized both hierarchically (through directories) and associatively (through links)

Different protocols approach hypertext differently:

  • HTTP/HTML emphasizes rich presentation with complex markup and embedded content
  • Gopher uses minimal menu structures with limited context
  • Gemini introduces simple hypertext with inline links and basic formatting
  • Scroll builds on Gemini’s approach while adding missing features necessary for large documents, like inline markup, nested lists, input links, and five levels of headings.

Scroll’s approach to hypertext emphasizes:

  • Semantic Links: Links can express relationships (agreement, disagreement, citation) to provide more context about why documents are connected
  • Document-Centric: Links connect whole documents rather than focusing on page-level navigation
  • Contextual vs Non-Contextual: Clear separation between document context (like link descriptions) and document metadata
  • Simple Markup: A streamable text format that supports basic formatting without the complexity of HTML
  • User Control: Presentation details are left to the client, focusing markup on structure and meaning

This approach aims to preserve the power of hypertext for connecting and organizing documents while avoiding the complexity and presentation-focused nature of the Web. By keeping hypertext simple but semantic, Scroll supports rich document networks that remain focused on content rather than display.

The Smallnet

The “smallnet” (or “smolnet”) refers to the collection of alternative internet protocols and their communities that emphasize simplicity, privacy, and human-scale interaction. This includes protocols like:

  • HTTP using minimal web pages
  • Gopher
  • Finger
  • Gemini
  • Spartan
  • Titan
  • Scroll
  • Nex

Unlike the modern Web, which has grown increasingly commercial and complex, the smallnet prioritizes:

  • Personal publishing and authentic expression
  • Simple, focused protocols
  • Human-readable content and formats
  • Privacy and user autonomy
  • Small, interconnected communities
  • Low bandwidth and resource usage

Scroll is designed to be part of this ecosystem, interoperating with other smallnet protocols (particularly Titan) while maintaining the core values that make the smallnet distinct from the Web. It aims to complement rather than compete with existing protocols, adding features like metadata and language support that benefit the broader smallnet community.

Why a New Protocol?

I originally wasn’t going to create any new protocols that mimic much of the same functionality as Gemini or Titan or Gopher. What changed my mind then?

The Scroll Protocol takes some inspiration from Gopher+. I read mozz’s journal entry about Gopher+ recently: => gemini://mozz.us/journal/2023-07-30.gmi Report: State of Gopher+, 2023

This led me to reading the Gopher+ spec: => gopher://gopher.floodgap.com:70/0/gopher/tech/gopherplus.txt Gopher+ Spec

And while reading this, even though there were a lot of convoluted things that Scroll deliberately does not take from Gopher+ (a scripts section?! yuck!!), there were a couple of interesting things that jumped out as being useful, particularly the metadata requests and the concept of abstracts.

In Gemini there is a lack of semantic detail. Gemtext files don’t have a standardized way of getting the publication date or modification date or even an author metadata field. However, we got around this by using gemsub feeds, but it is very often that I come across gemlog pages where the publication date is on the gemsub feed but not in the gemlog page itself! And what about other filetypes that also don’t include this metadata information, particularly text files? What if we just added these three extremely common metadata fields to all responses?

Gopher+’s Metadata requests are really interesting because they allow you to just get the metadata of a resource without actually getting that resource. This is actually really useful for browsers displaying information before getting the whole resource. This is even particularly useful for Search Engines and Crawlers to just check the existance of a resource, or whether it has been updated even, or to get its content type, before getting the actual file.

Gopher+ also adds in these “abstracts” to the Metadata requests. Abstracts offer a description of the file. This lets someone get a brief description of a file before spending resources downloading it. Abstracts in Scroll also offer the title of the resource so browsers and crawlers can get the title before downloading the resource. One use of an abstract could be to list the currently playing song of an audio stream within the abstract, and AuraGem’s public radio does just this.

All of the above, however, introduces a new concept: a distinction between contextual information and non-contextual information. When you link to a resource from a page, you title the link in a way that it’s contextual to that page. However, resource metadata is non-contextual; it doesn’t depend on the context of another page.

Both contextual and non-contextual information is useful, and this to me justifies the use of documents like in Gemini over file listings like in Gopher. Documents give information about files within the context of the rest of the document. File listings presumably give non-contextual information. However, gopher already blurs this boundary by allowing you to link to outside resources from a menu! And thus, links that should be non-contextual, like in a filesystem, become contextual as file links are placed in groups, categorized, and even duplicated among multiple menus. And yet gopher’s “i” itemtype that would explain this context, that would explain how a link relates to the rest of the links in the menu, is non-standard and frowned upon. Gemini makes the correct decision in allowing the already-blurred lines to be clarified by contextualizing links with text. Gemtext documents are better menus than gopher menus ever were for this simple reason: groupings of links (menus) can be contextualized and explained with text.

Mozz had it only partially right when he talked about the distinction of Documents and Directories in 2019: => gemini://mozz.us/journal/2019-08-20_documents_and_directories.gmi Documents and Directories

It is true that Gopher does distinguish between menus and documents, whereas the web does not. In the modern web, every page has become a document to the point that directories hardly even exist anymore. Gopher has “directories” that are more like groupings of links, aka. menus. Gemini ends up using the same markup for directories and documents; however, the distinction is still present: a gemtext directory is usually constructed differently than a gemtext document. There are some cases, however, where the lines are becoming a bit more blurred like they became in the web, and this mainly comes from the social media and other interactive capsules. Scroll takes much the same approach as Gemini, but it tries to reintroduce the distinction between directories and documents through convention (see the “Structure of Content” section in the spec), particularly the convention of what is expected of super-directories in URLs.

Contextual information lends itself towards semantic information when linking between pages. This is one of the few things that search engines really need but that nobody has effectively created a solution for: how do search engines know when a link to a page implies a positive or negative relationship? Search Engines that use pagerank currently assume all links imply a positive relationship. Scrolltext adds a very simple tag to the end of all links to identify these relationships. It is done in a human-readable way so that they are useful to users, and so that they don’t distract too much when the browser doesn’t support these tags.

Lastly, and the biggest addition to scroll that I think justifies and warrants its existance, is internationalization, which Gemini and Gopher sorely lack. Gemini offers a lang parameter on responses, and allows UTF-8, which is already more than Gopher does, but there is no way to request resources of a particular language without creating a whole different link to the resource adding some language tag to the beginning of the link’s path. Scroll solves this by adding a field to all requests for the languages the user desires, and then the server responds with a match for one of the languages, or a fallback if no matches.

I chose this method because the language should not be in links but be requested by the user’s client. Links assume everyone reads in the same language as the one who posted the link. Rather, it should be the client, not the content, that decides what language is requested, and clients can offer up multiple languages in the request instead of just one language if the user speaks multiple languages. This is such an easy addition that I think will vastly improve internationalization. It also means all error messages may be internationalized by the server!

For all of the reasons above, I felt that these additions were very simple additions, and yet powerful enough, to warrant the creation of a new protocol.

Scroll Network Protocol Specification

Conventions used in this document

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [BCP14].

Scrolltext Format

Mimetype: text/scroll File Extension: .scroll

The scrolltext format is a descriptive markup language inspired by Gemtext, Markdown, and AsciiDoc. It is designed to be streamable and easy to parse, and contains the most important elements within most textual documents, printed and digital. Scrolltext is therefore line-based, much like gemtext.

Sections and Headings

Unlike HTML, scrolltext is made up of sections that encompass a heading of a particular level and span up to the next heading of the same level. Sections are split up into sub-sections via higher-level headings. Headings, therefore, denote the start of new sections.

Heading lines are prefied with #, ##, ###, and an additional fourth-level heading #### and fifth-level heading #####, much like in gemtext and markdown. The first level-1 heading of a scrolltext page should be interpreted as the document’s title; there should be no other level-1 heading in the document. Clients may give sections heading numbers, like 1, 3.2, and 1.4.3. Dots delimit the level of the heading, where 3.2 refers to the second level-3 heading under the third level-2 heading. Note that the first number always denotes a level-2 heading.

Level-5 headings do not need to be placed directly under a level-4 heading; they may be placed under any heading levels 1-4. They are always considered textual titles rather than section titles, and therefore should be excluded from outlines and tables of contents (e.g., the titling of a paragraph or set of paragraphs).

Thematic breaks use three hyphens (---) on their own line. They are usually rendered as horizontal rules or three asterisks (which is the common rendering in printed books). They should be interpreted as thematic breaks within the section denoted by a level 1-4 heading. Note that they are never interpreted as being underneath level-5 headings.

Paragraphs

Each line with none of the line prefixes described in this document should be interpreted as paragraphs. Lines are not reflowed, but they may be word-wrapped.

Code Blocks

Code blocks define a block within the scrolltext that should be distinguished from the rest of the document as a textual format presented as plain text. They may be used for code blocks, ASCII Art, plain text, or other textual formats. They are usually presented visually in fixed-width fonts. Audial presentations should distinguish them from the surrounding text and should present the format tag to the listener.

Code blocks should not be word-wrapped or justified, but they may be character-wrapped. Code blocks are toggled with three backticks (```) on the start of a line. This toggle toggles the start or end of a code block.

The starting toggle of a code block may include an optional tag just after the three backticks that describes the format. Mimetypes starting with text/ are permitted, but the text/ prefix should be excluded. Therefore, text/plain should be written plain.

Examples of code block tags include:

  • ascii-art
  • plain
  • a programming language name
  • samp for sample software input/output

Quotes and Lists

Quotes are prefixed with >. They may be nested. Qutoed lines may be separated from each other by placing a blank line in between them.

Unordered lists (bullets) are prefixed with an asterisk followed by a required whitespace character (* ). It is the only linetype with a prefix that requires one whitespace character (a space or a tab). This is consistent because it is the only exception, an exception that allows one to distinguish between lines that begin with bold text (for clients that choose to render this) and unordered lists. Lists can be separated from each other by placing a blank line in between them.

Unordered bullets may be nested by placing two or more asterisks next to each other, up to a limit of 4, followed by a space, like so: ** nested bullet.

Ordered lists use asterisks like the unordered bullets above, but the text starts with any number of decimal digit unicode codepoints (e.g., Rust’s char.is_digit(10) or Golang’s unicode.IsDigit(r)), followed by a dot (‘.’), or by one character between ‘a’ and ‘Z’ followed by a dot. Rendering these differently from unordered lists is optional. Clients that choose to do so should render the number/character that was provided and not try to renumber the items. Ordered lists may be nested just like Unordered lists.

* Unordered list item 1
** 1. Ordered sub-list item 1
** 2. Ordered sub-list item 2
* Unordered list item 2

Quote and list item lines are not reflowed, but they may be word-wrapped.

Links use the following format:

=>(<whitespace>)URL<whitespace>Link Text

Whitespace may be any number of spaces or tabs above zero. The parentheses denote optionality.

The URL may be replaced with a #hash identifier to link to another heading/section of the current document. The hash for scrolltext documents should be the heading number described in the headings section (e.g., 3.2.4). Hashes on URLs should be interpreted as links to a section/heading within the linked document.

Links that are placed just under a quote should be interpreted as the citation for that quote. For example:

> This is a quote
=> scroll://example.net/cited_text.pdf Cited Text Name

See the “Link Relations” section below for metadata that can be attached to links, and may be optionally utilized or rendered by the client.

Lastly, when a user clicks on a link, clients may choose to inline the data depending on what contenttypes it supports. This is useful for images, audio, video, and even CSV files.

One may use an input link to denote a link that accepts a query string or data upload, depending on the scheme of the URL used. The link’s title should be seen as the input prompt. The input link may use a Scroll URL, or it may also use a Titan or Spartan URL, in which case the input should allow plain text upload or file upload, with some option to specify the mimetype where necessary. Scroll URLs do not allow data upload, and so should only use text and be requested via the query string. The syntax is as follows:

=:(<whitespace>)URL<whitespace>Prompt Text

Resources that change prompts depending on changing state may wish to use normal links to URLs that request input with the 10 and 11 status codes instead. The option of input links is provided for static prompts to support Spartan, and to allow for quicker input prompting for the other smallnet protocols.

If an unsupported protocol scheme is linked, the client should display the input in a way which reflects that to the user, and the input should be disabled.

Inline Markup

Strong, emphasis, and inline code blocks are semantic markup using toggles that are allowed inside paragraphs, list items, and blockquotes. The toggles are single asterisk, single underscore, and single backtick, respectively. Each toggle must have to one side a non-whitespace character that does not match the toggle character. A whitespace character in this instance includes the start of a document, the end of a document, newlines (CRLF and LF), tab, zero-width space (U+200B), and space. A toggle character that is between two symbols, as defined by Unicode’s punctuation and symbol categories, should not be interpreted as a toggle.

Inline code blocks may be used to delimit code, keyboard keystrokes, sample software input/output, or variables.

All inline markup may not extend past the line ending. This means a toggle that is not toggled off will automatically be toggled off at the end of the line it is placed in. In simpler terms, strong, emphasis, and inline code blocks cannot extend to multiple paragraphs, multiple list items, or multiple paragraphs and list items inside blockquotes.

Clients may choose not to present inline markup; however, it is highly recommended that audial clients parse them so that they can be presented differently from the surrounding text.

Linetype Escaping

All linetypes may be escaped using a backslash at the beginning of the line. This includes the following escaping combinations: \* through \****, \# through \#####, \>, \=>, \=:, “```”, and \---. The backslash should not be interpreted as an escape in all other cases outside of these combinations.

NOTE: This section on Link Relations is not final and may be changed or removed in the future.

When using a link, you can place a relationship identifier in square brackets after the link’s title text, like so:

=> scroll://example.net/sub/cited_text_name.txt Cited Text Name [Citation]
=> scroll://example.net/sub/cross-referenced_text.txt Cross-referenced Text Name [-Citation]
=> gemini://misfin.org Misfin Protocol
=> /submit_to_guestbook Action: Submit to Guestbook

> This is a quote
=> scroll://example.net/cited_text.pdf Cited Text Name [+]

All relative links are thought of as sections/categories/subdirectories/superdirectories, actions, or resouces. Links that provide a Scheme and Hostname that have no relationship identifier should be thought of as cross-references.

You can place a “+” or “-” in front of the relationship name, or by itself in brackets if there is no tag, to represent a positive or negative relationship. Negative relationships imply disagreement or critique, positive ones agreement or strengthening. When there is no “+” or “-”, the relationship should be interpreted as neutral.

Valid relationship identifier tags include: [Citation], [+Citation], [-Citation], [Cross-reference], [+Cross-reference], [-Cross-reference], [Alternate]

One may use custom relationship identifier tags, but one cannot expect clients to recognize and interpret them. The only tags guaranteed to be interpreted by all clients that care about these tags are those listed above. Clients may or may not choose to parse and display these identifiers in a way that’s distinct from the rest of the link; it is entirely optional. Lastly, tags should always be human-readable and can include spaces. Underscores in tags are heavily discouraged, and hyphens are cautioned against.

Parsing Scrolltext Streams

Scrolltext is primarily meant to be streamed. This allows a document to be displayed as it is being downloaded. Linetypes are identified by a prefix string on each line. Each linetype determins how the rest of the line should be interpreted. Code block toggles change the interpretation of the following lines by toggling code blocks on/off.

Within paragraphs, strong, emphasis, and monospace backticks should be interpreted as toggles that affect the following text within the line.

Procedural vs. Descriptive vs. Presentational

Scrolltext is a descriptive markup language, meaning linetypes dictate what lines are and how they should be processed. Scrolltext may be used procedurally in that documents can be translated from scrolltext to any other document format. In this way, the procedural vs. descriptive definitions are seen as a false dichotomy; all markup languages are “procedural” because all markup languages can be processed into other documents based on “instructions,” or markup tags. In descriptive markup languages, the processing of the document is a function of the descriptive markup.

Three backticks denote the start of code blocks, and may be seen as the only presentational markup within scrolltext. However, these code blocks are tagged with identifiers that describe the format of the contents, much like tags in XML and SGML languages, and so may be seen as descriptive.

Zero-Width Space

Zero-width spaces are used in languages that do not have visible spaces, like Myanmar, Japanese, Thai, and Khmer. Everywhere where word-boundaries in natural-language text are interpreted, zero-width spaces should be considered whitespace. For the purposes of inline markup, zero-width spaces should be considered whitespace. Outside of those two instances, they are not considered whitespace.

Non-visible characters should be prohibited in domain names to prevent homograph attacks. Browsers should error out when it sees non-visible characters in a domain name.

Request Format

All request headers must use UTF-8. The request format is the following:

<URI><space><LanguageList><CRLF>

The request must not begin with a U+FEFF byte order mark.

The URI is a UTF-8 encoded absolute URL, including a scheme, without URI parameters. Servers should error out on URLs that have parameters rather than ignore them.

The language list is a comma-delimited list of BCP47 strings. Which languages go into the list should be handled by the client, so that every request uses the client’s default language(s). Servers should respond to all requests by matching the desired languages in the list to the available languages and serving the content in the best match. Languages provided earlier in the list should be interpreted as more desired than those at the end of the list. If there is no match, the server may choose a default language, or leave it unspecified.

Servers should always prefer the language list over any site settings in their user database. The use of language settings in site databases is heavily discouraged; they are no longer needed.

Clients must not send anything after the first in a request, and servers must ignore anything sent after the first .

Error and Input Responses

Must be in UTF-8. Format is the following:

<Status><space><Description><CRLF>

The Description may or may not be in one of the requested languages. It may also be blank. If it is blank, a space is still required between the Status and the Description. If the status is “10” or “11” (Input or Sensitive Input), then the Description should be interpreted as the Input Prompt.

Status codes remain the same as in Gemini.

Success Response Format

The response format uses the following for the 20-29 (success) status codes. The response’s header (including the metadata information) must be in UTF-8. The data’s charset is determined by the mimetype. If charset is unspecified, then clients might want to detect the charset for text files.

The format is the following:

20<space><Mimetype><CRLF>
<Author><CRLF>
<PublishDate><CRLF>
<ModificationDate><CRLF>
<Data>

All dates are in UTC and ISO8601 format. The mimetype should contain the language parameter for natural-language text files. If any metadata is empty/unspecified, then its respective line is blank, ending in a . All other status codes remain the same as with Gemini.

Note that ISO8601 is similar to RFC3339, but not exactly the same. You may get away with using RFC3339, but this “spec” standardizes on ISO8601. The “Z” suffix is required in all dates.

Success Status Codes

The success status code’s first digit is ‘2’ and the second digit designates the categorization of the content, based on the main classes of the UDC (Universal Decimal Classification) system:

    1. General Science, Knowledge, Documentation (books, writings, authorship, software, software repository info), Reference works as subject (Encyclopedias, Dictionaries, Translators, etc.), Computer Science, News, Protocol RFCs, Data, software development logs, computer technology
    1. Philosophy (Ethics, Epistemology, Metaphysics, Metaphilosophy, etc.), Psychology
    1. Religion, Theology, Scripture
    1. Social Sciences (Law, Politics, Economics, Sociology, Education, Gender & LGBTQ+ Studies, etc.), Military affairs
      • Default, General menus/indexes/directories/aggragator lists to internet resources, Misc., Unclassed media/software
    1. Mathematics, Natural Science
    1. Applied Science, Medicine, General Technology, Engineering
    1. Arts (Photography, Culinary, Painting, Fashion, Beauty, performance, etc.), Entertainment (Music, Gaming Videos, Fictional Movies and Animation and TV Shows, etc.), Sport, Fitness
    1. Linguistics, Literature, Literary Criticism, Memoirs, Personal Blogs/gemlogs/scroll-logs, Book/Movie/Video reviews
    1. Geography, History, Biography

When a document is unclassed, it should use class 4, meaning the status code should be 24.

Non-entertainment media (usually non-fiction) should be placed in their correct category, even if they are video or audio. For example, a Theology Documentary should be placed in class 2.

Media or documentation about software should be in class 0, whereas software (binaries, zips, packages, internet apps) itself should be based on the topic that software covers. Document readers, browsers, chat or social media, etc. should be placed in class 4, along with any other software that doesn’t fit in any of the other classes.

Computer Science (class 0) includes information about computer architecture, hardware, software, human-computer interaction, AI, etc.

Metadata Request

Must be in UTF-8. A metadata request puts a “+” at the beginning of the language list:

<URI><space>+<LanguageList><CRLF>

Success Metadata Response

Response header (including the metadata information) and the abstract must be in UTF-8. The response format is:

20<space><Mimetype><CRLF>
<Author><CRLF>
<PublishDate><CRLF>
<ModificationDate><CRLF>
<Abstract>

The mimetype, author, publish date, and modification date are of the file, not of the abstract. The Author can be the user that created the file, the Author metadata from within the file (if supported in its data format), or the Author metadata specified elsewhere on the server. The Abstract is scrolltext that briefly describes the resource. The abstract should always include a level-1 heading of the title of the resource, but other text is optional. It may or may not be in one of the requested languages.

Error and Input Metadata Response

When metadata is requested from a URL that gives back an error or Input, the same error/input response is given back:

<Status><space><Description><CRLF>

Client Behavior

The behaviors that are expected of a client are listed below:

  • Clients should not make automatic requests without a user interaction or an intentionally set user option. Metadata/Abstract requests are the only exception.
  • When input is requested, the input should never be concatenated with the current URI’s query string. Rather, the input overwrites the current query string in the new request.
  • Query parameters and URI parameters should never be used.
  • The end of a file or stream occurs when the server closes the connection. A client could optionally detect an orphaned connection by checking the last time since bytes were received on the connection and prompting the user.

Streaming

Scroll explicitly allows for streaming text and binary data by allowing clients to deal with data as it comes in. While this is best practice, it is completely optional, and might be handled differently depending on the content type of the response body.

It is highly recommended that for all clients that support playing audio and video, all streamable audio and video contenttypes are played as they come it rather than waiting for the full file to download before playing. This could be done by playing directly or by piping the file data to another application.

Titan

All clients and servers should ideally support the Titan protocol.

=> gemini://transjovian.org/titan Titan Protocol

TLS and SNI

TLS 1.2 and above is required for all servers. Server certificates should have all domain names in the SAN. The Common Name can be the primary/default domain name. Clients should try to use TLS 1.3. TOFU is used, similarly to Gemini. All clients must send the requested hostname via SNI. Servers may choose to read the hostname from SNI if they wish, but it is not required.

Client Certs

Client certificates may also be used. The USER_ID field of the certificate should always be interpreted as the user’s desired username, unless empty. Note that it could have spaces.

If the USER_ID, CommonName, and SAN fields are provided, then the certificate should be interpreted as a misfin certificate and can be used by the server to send misfin messages to the user’s misfin mailbox.

=> gemini://misfin.org

Security.txt and Robots.txt

A robots.txt may be used to specify which links a bot may crawl. The user-agents to use are similar to the ones specified by gemini’s robots.txt spec. Crawl-delays are allowed in robots.txt so that crawlers may know the rate-limiting before it occurs. Security.txt may also be provided for security information.

BCP47 Language Tags

BCP47 Language Tags consist of a primary tag with a optional subtags appended with a hyphen. Ex: “en” vs. “en-US”. Subtags usually specify a variant of a language, a script, a region, or an extension. The syntax of a language tag as specified by RFC 5646 is the following: language [‘-’ script] [‘-’ region] *(‘-’ variant) *(‘-’ extension) [‘-’ privateuse] Common Language tags: “en” for English, “fr” for French, “de-CH” for Swiss German, “zh-Hans-CN” for Chinese, Simplified Script, as used in Mainland China

=> https://www.rfc-editor.org/rfc/rfc5646.txt RFC 5646

Tor and i2p

Scroll servers may be hosted on Tor or i2p, however, they must still use TLS and self-signed certs with the onion/i2p addresses in the SAN field.

Document Formats

Scrolltext

The Scrolltext hypertext document format is heavily influenced by Gemini and Markdown.

Paragraphs and Inline Markup

Paragraphs act like Gemini paragraphs. Each line with none of the line prefixes described in this document below should be interpreted as paragraphs. Lines are not reflowed, but they may be word-wrapped.

Strong, emphasis, and inline code blocks are semantic markup using toggles that are allowed inside paragraphs, list items, and blockquotes. The toggles are single asterisk, single underscore, and single backtick, respectively. A toggle character that is between two symbols, as defined by Unicode’s punctuation and symbol categories, should not be interpreted as a toggle.

Inline code blocks may be used to delimit code, keyboard keystrokes, sample software input/output, or variables.

This is a *paragraph* with _inline markup_ for the scroll protocol's `scrolltext`.

All inline markup may not extend past the line ending. This means a toggle that is not toggled off will automatically be toggled off at the end of the line it is placed in. In simpler terms, strong, emphasis, and inline code blocks cannot extend to multiple paragraphs, multiple list items, or multiple paragraphs and list items inside blockquotes.

Clients may choose not to present inline markup.

Headings

# Level-1 Heading
## Level-2 Heading
### Level-3 Heading
#### Level-4 Heading
##### Level-5 Heading

Thematic Break

---

Code Blocks

Code blocks are semantic. They specify a content-type tag, and a block of the given textual content-type.

Examples of code block content-type tags include:

  • ascii-art
  • plain
  • a programming language name
  • samp for sample software input/output

An example is given below:

```C
void main() {
  // C program here.
}
```

Quotes and Lists

Quotes use Markdown syntax. Lists use AsciiDoc syntax.

> Quote here

*  List item 1
** Nested list item
*  List item 2

Ordered lists are bullets prepended with a number and a ., like so:

*  1. List item
** Nested item
*  2. List item

Links use Gemini syntax. They must be placed on a line on their own.

=> scroll://auragem.ddns.net/ AuraGem Scrollery

Input Links are a concept taken from Spartan (and Gemini) that allows the browser to immediately ask for input before having to make a server request, or show an editable textbox in place of the link. Their syntax is very similar to Gemini link syntax:

=: scroll://auragem.ddns.net/search/s/ AuraGem Search

Clients

Clients allow you to browse scrollspace and read scroll documents, much like a web browser browses the web:

Profectus

Overview

Profectus is a new GUI smallnet browser built in SDL to rival lagrange in terms of performance, visual design, and features. It is currently in beta 1.1 and supports nex, gemini, spartan, and scroll, as well as music streaming (mp3, vorbis, flac, and wav), and animated images (gif, apng, jpeg xl, avif).

Gitlab Repository
Flathub Download
Precompiled Binary Download

Recent Updates

  • Beta 1.2 contains new settings file and support for Flatpaks and macOS bundles
  • Beta 1.1 removes libwebp support.
  • Beta 1.0 contains new themes, finished outline, and scroll metadata info in sidebar.
  • Alpha 0.10 contains Spartan support, two new themes based on firefox, and address-bar searching.
  • Alpha 0.9 contains theming, Ctrl+T and Ctrl+Shift+T to shuffle between themes, basic theming documentation, and more UI animations.
  • Alpha 0.8 contains smooth scrolling, animatted tabbar, and Ctrl+B to show/hide the sidebar.
  • Alpha 0.7 contains tabs, animated AVIF image support, optimized text rendering, and memory leak fixes.
  • Alpha 0.6 contains support for animated JPEG XL and WebP image files, fixes for animated PNGs (APNGs), and a fix for images getting cut off.
  • Alpha 0.5 contains support for animated GIFs and animated PNGs, a slightly increased scrolling speed, and some small performance and memory optimizations.
  • Alpha 0.4 contains the final fixes for DPI, improvements to the styling of quotes, Ctrl+Shift+Plus/Minus shortcut to manually increase/decrease the UI scale, fixes to hover/click events (they are clipped properly), and support for youtube:// and ytdl:// links.
  • Alpha 0.3 contains more proper fixes for DPI on Wayland and macOS, as well as very basic CSV file support.
  • Alpha 0.2 contains quick fixes for DPI on Wayland Linux systems.

Servers

You can run your own Scroll server by choosing one of the following:

Smallnet Information Services

Smallnet Information Services (SIS) is a server software suite that plays a similar role to Microsoft’s Internet Information Services (IIS), but for protocols in the small internet ecosystem. SIS provides integrated server support for Gemini, Gopher, Nex/NPS, Spartan, Misfin, Scroll, and Titan protocols. Using the built-in SIS Manager interface (accessed via Gemini), administrators can configure and manage multiple virtual servers across different protocols, defining their hostnames, certificates, and protocol-specific settings from a single administrative console.

Gitlab Repository
Documentation