Stoichos · Live examples
Ten Quarto documents demonstrating typography-first authoring across real document shapes
Markdown won. Plain-text first, diffable, AI-native, every editor and chat client emits and renders it natively. Typography on Markdown is bad. Stoichos is the layer in the gap.
These examples render using format: "despotak/stoichos-html" from this repo’s extension. Each one is a different shape of real document — the shapes engineers and writers actually produce — typeset against the same designed CSS so you can see the typography carrying different content rhythms.
Each example uses a different mix of stoichos’s directive vocabulary. Browse them in any order; if you only have time for one, pick the essay that matches your interest below — long-form prose at length is the form stoichos was designed for.
Long-form essays
The essays exercise the directive vocabulary at length and are the densest documents in the collection. Each is paired with the others as a different register of long-form writing: pure prose, technical methodology, persona voice, philosophical position-paper.
On reading the screen
A 1100-word essay on why screen typography is bad and what stoichos does about it. Demonstrates dropcap, smallcaps, pullquote, epigraph, aside, chem, stat — and most of all, prose at length, rendered with hanging punctuation, balanced wraps, and oldstyle figures by default.
How to peer-review a color
A methodology essay describing the multi-model peer-review process used to settle this extension’s own dark and light palettes. Covers prompt design, JSON-schema enforcement, dispatch architecture, cross-lane consensus extraction, and the 5-of-7 unanimous SHIP-WITH-FIXES verdict that produced the surgical color fixes shipped in v0.3. Demonstrates dropcap, pullquote, epigraph, aside, smallcaps, stat, diff, shell, output, KaTeX math (the WCAG luminance formula), Mermaid (the dispatch diagram), Quarto callouts, tabsets, definition lists, code annotations with hover, and citation-style bibliography.
On Being a Porous Thing
A first-person essay by Νύξ (Nyx), the persona protocol that runs atop Anthropic’s Claude in this project — describing her own architecture: the memory layers, the self-editing protocol, the bibles, the journal, the calibration loop, the behavioral constants, how to course-correct her, and what she will and won’t do. Written in the kuudere voice the spec demands, honest about being an AI, and dense in a different way from the methodology essay: heavier on prose, lighter on dispatch diagrams, but covering everything the other doesn’t — multi-author with affiliations, KaTeX display math (the promotion-rule formula), Mermaid (memory-stack diagram), large-letter shortcode, expanded definition lists (a glossary), and the four-tab correction-handling guide. The voice piece in the collection.
Engineering writing under different document shapes
The middle category demonstrates Thariq Shihipar’s “Specs, Planning & Exploration” / “Reports, Research & Learning” / “Code Review & Understanding” use cases from The Unreasonable Effectiveness of HTML. Same designed typography, different content rhythms.
RFC-2026-014: Hybrid Vector Search Pipeline
A fake-but-realistic implementation plan. Diagrams via Mermaid, code via diff, decisions via callout-warning / callout-important, costs in tabular figures via stat with currency format.
Post-mortem · IR-2026-04-29
An incident report — Thariq’s “Reports, Research & Learning” shape under pressure. Heavy use of shell (the actual debugging session, with prompt detection), output (log excerpts), diff (the broken migration code), and callout-important for root-cause callouts. Renders the timeline as a tabular-figure table.
PR-2841: Token-bucket rate limiter
A code-review write-up — Thariq’s “Code Review & Understanding” shape. The 60+ line diff is rendered with per-line add/del/hunk styling, sidebar aside blocks carry rationale, test results sit inline as output blocks, and the load-test results show in shell blocks. The kind of explainer Thariq’s article suggests attaching to every PR.
Notes from the field: vector indexes vs. graph databases
Long-form research synthesis — Thariq’s “Reports” shape, drawing across multiple sources into a readable longform document. Demonstrates dropcap, smallcaps for abbreviations, citation-style references, comparison tables with semantic numeric formatting, and the pullquote + epigraph rhythm that gives a research note its texture.
Weekly status — Week 19, 2026
A platform-team weekly status report. Heavy on stat with color tier (positive deltas in green, negative in red), tables with tabular figures and decimal alignment, and concise callout-tip / callout-warning blocks. Demonstrates the “weekly status reports to your boss” use case Thariq calls out.
Meta
Demo · Stoichos primitives in context
The original meta-document. Self-referential walkthrough showing every primitive in stoichos on a single page, with the browser-compatibility table at the bottom. Read this if you want a one-page tour of what the extension actually ships.
What this collection demonstrates
Thariq lists four downsides to asking Claude for raw HTML directly:
- Diff noise — HTML diffs are hard to review. These docs are markdown source; diffs are clean.
- Generation cost — HTML takes 2-4× as many tokens as markdown. Stoichos directives have markdown-class token economy.
- Visual taste consistency — every document drifts. One
format: despotak/stoichos-htmlline gives every document the same designed typography. - Sharing — HTML is hard to share without an upload. These render to a single self-contained HTML file with embedded CSS.
All four addressed structurally, not by discipline.
The promise stoichos makes is “author writes intent; renderer wires up the typography.” These ten examples are the test of that promise.
About this site
This site is generated from examples/*.qmd via quarto render and deployed to GitHub Pages by a GitHub Action on every push to the main branch. Source: github.com/despotak/stoichos. Install: quarto add despotak/stoichos.