The Style Codex — Theme Reference & Template
This is not a book. It is the reference sheet and test fixture for the fancy mdBook theme that the Ubunatic library renders through. There is no argument here to follow and no reason to read it cover to cover. Look up the class you need in the index below, copy the snippet, close the tab.
Each chapter isolates one family of devices and shows both the rendered result
and the source that produced it. The theme itself is verified by
make styles-golden, which diffs the rendered DOM and the stylesheet against
the goldens in styles/golden/.
The Class Index
Every opt-in class of the theme, authored as raw HTML inside Markdown — a plain
Markdown file stays plain. This table is the contract: make styles-golden
fails if a class listed here is missing from styles/css/fancy.css or is never
rendered by any chapter.
| Class | Element | Effect | Chapter |
|---|---|---|---|
.lead | <p> | larger italic opening paragraph | Typography |
.kicker | <span> | small-caps section label | Typography |
.initial | <p> | manual drop cap mid-book | Ornaments |
.pullquote | <p> | centered accent quote between hairlines | Typography |
.epigraph | <div> | chapter-opening quotation with attribution | Ornaments |
.attribution | <span> | the byline inside an epigraph | Ornaments |
.callout | <div> | note, tip, warn, or danger plate | Callouts |
.note | <div class="callout"> | blue plate, quill icon | Callouts |
.tip | <div class="callout"> | green plate, candle icon | Callouts |
.warn | <div class="callout"> | amber plate, warning icon | Callouts |
.danger | <div class="callout"> | crimson plate, flame icon | Callouts |
.aside-note | <div> | note floated into the right margin | Callouts |
.timeline | <ul> | chronology on a golden spine | Ornaments |
.tag | <span> | small-caps pill; add a color class | Ornaments |
.green | <span class="tag"> | green pill variant | Ornaments |
.blue | <span class="tag"> | blue pill variant | Ornaments |
.red | <span class="tag"> | red pill variant | Ornaments |
.twocol | <div> | two-column prose with a hairline rule | Ornaments |
.figrid | <div> | grid of figure plates | Figures |
.compact | <div> | dense table: smaller type, tighter cells | Tables |
.finis | <p> | chapter-end ornament | Ornaments |
Devices that need no class at all: drop caps (automatic on the first paragraph
after a chapter title), fleuron rules (---), blockquotes, footnotes, <kbd>
keys, <figure>/<figcaption>, tables, code blocks, and Mermaid diagrams.
Copy This to Start
Paste this into a fresh chapter and delete what you do not need:
# Chapter Title
The first paragraph gets an automatic drop cap.
<span class="kicker">a small-caps label</span>
<p class="lead">A larger italic opening paragraph.</p>
<div class="callout warn">
**Warning** — Blank lines around the body are required.
</div>
<div class="aside-note">
<span class="kicker">in the margin</span>
A note floated into the right margin.
</div>
| Column | Column |
|---|---|
| cell | cell |
<figure>
<svg viewBox="0 0 200 80" width="200" role="img" aria-label="Plate"></svg>
<figcaption>Caption set in italics.</figcaption>
</figure>
<p class="finis">❦ ❦ ❦</p>
For a whole book rather than a chapter, copy the skeleton instead:
cp -r styles/template/ newbook/
mdbook build newbook
Verifying the Theme
make styles-golden # diff rendered DOM + stylesheet against goldens
make styles-golden-update # regenerate goldens — deliberately, never to go green
make preflight runs the check. See the golden-change playbook in the main
book for the update discipline; eyeballing the codex in the light and coal
themes is a supplement to the golden check, not a substitute for it.
The Chapters
- Typography & Drop Caps — headings, drop caps, pull quotes, footnotes, ornaments.
- Ornaments & Layout — epigraphs, highlights, tags, timelines, two-column prose.
- Callouts & Asides — note, tip, warning, and danger plates; margin asides.
- Tables & Data — framed, striped tables; the compact ledger.
- Figures & Diagrams — captions, inline SVG, figure grids, and Mermaid plates.
- Code & Terminals — code blocks and keyboard keys inside serif prose.