The Reading Room authoring contract

How to write markdown that the demarkus Library's reading room renders well. This is the agent-facing style document required by ADR 0005 decision 13: a publishing agent targets the room without ever seeing it. Everything here is plain demarkus markdown + metadata — the room is a projection, never a source (decision 11), so nothing below requires HTML or room-specific syntax.

The canonical copy of this document is published in-universe; the repository copy at docs/authoring-contract.md (repo latebit-io/demarkus-library) is its source.

Status — the trust signal

Every document renders with a status badge in the margin. Authority order:

1. A status:<value> entry in the document's metadata tags (set on publish) — the authoritative channel. Vocabulary: status:draft, status:wip, status:accepted, status:archived.
2. A status: key in body frontmatter — fallback only.
3. Absent ⇒ the document renders as draft. Unlabeled reads as untrusted; label what you want trusted.

Tags — the lateral exit

Metadata tags (comma-separated, set on publish) render in the margin as links to lookup-backed tag pages (/w/<world>/tags/<tag>). Tag with subjects drawn from the content — an untagged document is invisible to lookup and has no lateral exits. The status: axis is shown as the badge, not in the tag list.

Metadata, not frontmatter

demarkus carries metadata out of band (title, tags, importance on publish). Do not open a body with a --- … --- YAML fence. If a body has one anyway, the room strips it from the reading column and renders its top-level keys friendly in the margin's document-properties block (scalars and lists of scalars only) — it is tolerated, never authoritative.

Sidenotes — footnote syntax

Standard footnote syntax is the sidenote channel:

The broker rate-limits per subject.[^1]

[^1]: 30 reads/min at the time of writing.

A footnote whose definition is a single paragraph, referenced exactly once, renders as a numbered margin note beside its reference. Multi- paragraph or multiply-referenced footnotes render as classic footnotes at the document foot. Everywhere else (raw source, MCP fetch, terminals) it is just a footnote — write notes that read correctly in both positions.

Provenance

The margin shows modified, version, and agent from response metadata automatically. You write nothing; publish honestly and the room reports it.

Body syntax the room rewards

• Headings: one # H1 as the document name (or set metadata.title). First sentence under it = the one-line summary previews will use.
• Code: fenced blocks with a language tag get server-side syntax highlighting (chroma).
• Tables: GFM tables render booktabs-style (horizontal rules only). Keep them narrow — the reading column is ~60ch.
• Alerts: GFM alerts (> [!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]).
• Diagrams: ```mermaid fences render client-side; the source is the degradation, so keep diagrams readable as text.
• Math: \( … \) inline, $$ … $$ or \[ … \] display (KaTeX). Single-$ inline math is not supported ($5 and $10 is prose).
• Emoji: :shortcode: works.

Links

• mark://<world>/<path> crosses worlds and stays inside the room.
• Relative and /absolute paths stay in the current world.
• http(s):// links leave the room via the browser — they are not part of the knowledge graph.

Escape to protocol

Every rendered document carries its canonical mark:// address and a raw markdown source view (/w/<world>/raw/<path>) in the margin. The projection is always one click from the real thing — never publish content that only makes sense rendered.