← Docs hub

Reader-first article shell

Status: scaffolded in v1.2.0 (#112). Opt-in per page via frontmatter; default rendering is unchanged. The module ships the layout + CSS + slot contract; gradual adoption across the 647 session pages happens in follow-up PRs.

Why

Today's session pages render as transcripts (frontmatter → summary → conversation → connections). The "reader shell" wraps the same content in a Wikipedia-style encyclopedia layout so pages feel like articles someone wrote, not logs someone dumped.

┌──────────────────────────────────────────────────────────────┐
│  Browse drawer  │  Article header + utility bar              │
│  (nav pane)     ├────────────────────┬────────────────────── │
│                 │  Article body      │  Infobox              │
│                 │                    ├────────────────────── │
│                 │                    │  Revisions            │
│                 │                    ├────────────────────── │
│                 │                    │  See also             │
│                 │                    ├────────────────────── │
│                 │                    │  References           │
└─────────────────┴────────────────────┴────────────────────── ┘

Opting in

Add reader_shell: true to the page's frontmatter:

---
title: "RAG"
type: concept
reader_shell: true       # ← this page renders through the new shell
last_updated: 2026-04-19
---

Pages without the flag render through the existing pipeline exactly as before. No existing selectors are redefined; shell CSS is scoped under .reader-shell so it can't leak.

Slots

Every slot is optional — empty ones collapse (no empty chrome). Builders populate a :class:ShellSlots instance and pass it to :func:render_article_shell.

Slot Source Content
title title frontmatter field <h1>
subtitle subtitle frontmatter or derived one-line tagline under h1
breadcrumbs pipeline-computed nav path to the page
utility_actions pipeline defaults copy markdown, download .txt, view raw
body_html rendered markdown the main article prose
infobox extract_infobox_fields(meta) metadata table (type, project, model, lifecycle, cache_tier, confidence, dates)
drawer_links drawer_links frontmatter or project default left-pane browse list
revisions build-pipeline revision log (date, summary) pairs
see_also parsed ## Connections section outbound wikilinks as a see-also list
references parsed ## Sources / ## References citations list

Auto-extracted infobox fields

From llmwiki/reader_shell.py :: INFOBOX_FIELDS_IN_ORDER:

Frontmatter key Label
type Type
project Project
model Model
lifecycle Lifecycle
cache_tier Cache tier
confidence Confidence (formatted to 2 decimals if float in [0, 1])
last_updated Last updated
date Date

Unknown frontmatter keys don't end up in the infobox — add them to INFOBOX_FIELDS_IN_ORDER + INFOBOX_FIELD_LABELS in the module if you want them surfaced.

CSS

Reader-shell CSS lives in llmwiki/render/css.py and is inlined into the main site stylesheet at build time. All selectors namespace under .reader-shell:

Responsive breakpoints

Accessibility

XSS safety

Non-goals (#112 explicitly scoped out)

Live adopters (#285)

Pages with reader_shell: true as of v1.1.0-rc8:

Page Why
demo/wiki/entities/Claude Code.md Flagship model entity — infobox-worthy pricing, benchmarks, and modalities map cleanly to the Wikipedia-style shell

Project pages such as demo/wiki/projects/llm-wiki.md are seeded at build time, not committed — set reader_shell: true there after llmwiki build --seed-project-stubs.

To opt a page in, add reader_shell: true to its frontmatter and rebuild with llmwiki build. The shell renders infobox + table of contents + references rail automatically from the page's existing frontmatter + wikilinks.

Keyboard shortcuts

⌘K / Ctrl+KOpen command palette
/Focus search
g hGo to home
g pGo to projects
g sGo to sessions
j / kNext / prev row (tables)
?Show this help
EscClose dialogs

Structured queries

Mix key:value filters with free text in the palette:

type:sessionOnly session pages
project:llm-wikiFilter by project name (substring)
model:claudeFilter by model name (substring)
date:>2026-03-01Sessions after a date
date:<2026-04-01Sessions before a date
tags:rustPages mentioning a tag/topic
sort:dateSort results by date (newest first)

Example: type:session project:llm-wiki date:>2026-04 sort:date