t-deckard/decktext-spec.md

# DeckText specification and manual

DeckText is a strictly defined subset of HTML (Hypertext Markup Language) aimed at simple, lightweight, text-only document authoring with basic formatting and page-oriented structure for consumption on low-powered portable devices with line-oriented UI, while being backwards-compatible with any existing Web browser implementation.

## Rationale

Rendering full HTML is a very compute-intensive task, especially for the devices that do not need all the features. A subset that would allow conveying all required text-only information, keeping the parser as simple as possible (while still being backwards-compatible with the original HTML specification), is a necessity for such devices without having to switch to alternative "small Web" protocols such as Gopher, Gemini, Nex or Spartan.

## General definitions

A **DeckText site** is a simple HTML document that conforms to this specification. Although it is allowed to have multiple HTML documents, it's recommended for the entire site to be served as a single-file HTTP(S) download.

A DeckText site consists of:

- document title,
- DeckText beginning and end markers,
- page separators,
- page contents consisting of a strict subset of HTML tags.

A **DeckText-only client** (henceforth DTOC) is a software application that allows its users to browse DeckText sites without needing to implement a full HTML rendering engine.

DTOCs MUST support UTF-8 encoding inside the documents and render them accordingly. Particular Unicode character set availability outside ASCII range is not required as it depends on the fonts installed on the target device.

## Beginning and end markers

To mark the beginning and the end of a DeckText-compliant document fragment within an HTML page, the following case-insensitive markers are used:

- `<!-- decktext_begin -->` marks the beginning of DeckText,
- `<!-- decktext_end -->` marks the end of DeckText.

A single HTML page MAY contain several begin-end marker pairs, and a DTOC MUST read through all these sections and compile the document to display from all of them. 

Between the begin-end markers, only text content is allowed.

## Title

Just like any HTML document, a valid DeckText document MUST contain a single `<title></title>` tag. A DTOC MUST read and display its contents to the user as a document/site title. The tag MUST NOT have any attributes and MAY be placed outside any other HTML element.

This tag is the only one that is not required to be placed between the DeckText start and end markers in order to be read by a DTOC.

## Pages

Every DeckText document is split into logical pages, which may or may not match physical pages on the target device.

The horizontal rule element (both `<hr>` and `<hr />` forms are allowed) is solely defined as the **page separator**. DTOCs MUST split the document by this separator and offer the user to switch between pages based on it.

Any content between the first DeckText start marker and the first page separator forms the first page of the document.

It is recommended for the first page of the document to contain its overall description and a table of contents with the corresponding page numbers.

## Page content

When displaying page content, the following rules apply:

1. All opening and closing tags not supported by the client are ignored.
2. Whitespace IS NOT collapsed.
3. All newlines ARE preserved.
4. Lines longer than the viewport width MUST wrap.
5. Display font SHOULD be monospace, unless the target platform does not support it.

## Supported HTML tags

DTOCs MUST implement these tags:

- `<!-- decktext_begin -->` to mark the beginning of DeckText-compliant document fragments
- `<!-- decktext_end -->` to mark the end of DeckText-compliant document fragments
- `<title></title>` for document title display
- `<hr>`, `<hr/>`, `<hr />` as a page separator
- `<a href="(link)">Link name</a>` for defining hyperlinks (see "Link processing" section for details)
- `<b></b>`,`<strong></strong>` for bold text
- `<i></i>`,`<em></em>` for italic text
- `<tt></tt>`,`<code></code>`, `<pre></pre>`, `<xmp></xmp>` for code text
- `<s></s>`,`<del></del>` for strikethrough text
- `<q></q>`, `<blockquote></blockquote>` for quoted text
- `<li></li>` for list items (all lists are considered unordered)

Nesting any of these elements is NOT supported in DeckText. In case such nesting occurs, a DTOC MAY display the inner element contents verbatim, process it correctly or throw a parsing error, depending on the implementation.

DTOCs MUST NOT implement attribute support for any tag except `<a>`, and only the `href="..."` attribute is required to be supported.

Tag support is case-insensitive but mixed case IS NOT supported. I.e. within a single opening/closing tag, all letters MUST be either uppercase or lowercase: `<TITLE>` and `<title>` are supported but `<Title>` is not.

## Link processing

Whenever an `<a>` tag is encountered within the DeckText block, a DTOC MUST do the following:

1. Look for the matching `</a>` tag and record the link label.
2. Look for the `href=""` attribute within the opening `<a>` tag and extract the link URL. The URL inside the `href` attribute MUST be wrapped in double quotes (no other quotes allowed).
3. Provide a clear UI for the user to visit the URL when selecting the link label.

A DTOC also SHOULD implement anchored page URLs in the form of `#{page_number}` links, e.g. `<a href="#5">Page 5</a>`, for easy navigation within the DeckText site. This is not mandatory because a DeckText client itself should provide a convenient UI for navigating by page numbers.

## DeckText compatibility with "traditional" Web browsers

In order for your DeckText documents to display normally in both DTOCs and full-featured Web browsers according to this specification, the following HTML template is recommended:

```html
<!DOCTYPE html>
<html><head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width,height=device-height,user-scalable=no,initial-scale=1.0"/>
  <title>Your Document Title</title>
  <style>
    *{font-family:monospace;font-variant-ligatures:normal;white-space:pre-wrap;tab-size:4}
    hr{margin: 1em 0}
    /* ... other desired CSS styles ... */
  </style>
</head><body>
<!-- decktext_begin -->
<!-- ... your valid DeckText markup here ... -->
<!-- decktext_end -->
</body></html>
```

Keep in mind that any valid DeckText markup is also valid HTML markup, but not vice versa. Make sure you adhere to the rules provided in this specification.

## Credits

The original version of this specification was created by [Luxferre](https://luxferre.top) and published in December 2025.

The specification and reference DTOC implementations are released into public domain with no warranties.