A card
Grouped boxes. Good for key points, and for red flags beside green ones.
Elements
This page is built on every npm run ci, and that is the whole point of it. It has one job:
if an element renders wrongly, it renders wrongly here first — once, on a page nobody is
reading — instead of inside a pasted chapter, where the defect is tangled up with content you were
trying to judge on its own terms.
It is the ceiling made visible. Everything on this page is available to a chapter. Nothing else is. A paste using something absent here is a defect in the paste, not a feature request.
The four custom components
Section titled “The four custom components”Everything else composes from stock. These four exist because the reading protocol produces something Starlight cannot express.
<Recall>
Section titled “<Recall>”minutes is optional and defaults to 10. Deliberately reads as a wall, not a note — it is
the closed-book section, and the AI never writes inside it.
Book shut, page collapsed, assistant off. Write what the chapter argued, in your own words. Then the questions you could not answer.
Book shut. Newport’s argument, as far as I can reconstruct it: attention is the scarce input to knowledge work, the tools that fragment it are economically rational for their makers and irrational for me, and the fix is structural rather than motivational.
What I could not answer: whether he ever addresses work that is genuinely interrupt-driven, or whether the whole book assumes a job I do not have.
Then the same element with no minutes, which is how most chapters will use it:
Book shut, page collapsed, assistant off. Write what the chapter argued, in your own words. Then the questions you could not answer.
One sentence is a legitimate recall. A bad recall recorded honestly is worth more than a good one written with the page open.
<Actions />
Section titled “<Actions />”No children. It reads actions: from the frontmatter, because actions are data and writing
them twice guarantees the two disagree. Both actions above render below — note the id printed
visibly on each card, which is what makes a rename something you can see.
- Reference
el-01-renderIf a component renders wrongly on this pagethen I fix it here before it reaches a chapter
- Reference
el-02-ceilingIf a chapter needs something not on this pagethen I say it in one sentence instead, or ask for a fifth component in writing
<Passage>
Section titled “<Passage>”at is optional and carries the location. This is the only element on a chapter page whose words
came out of the book, and it looks different because its provenance is different.
The metric of busyness became a proxy for productivity precisely because knowledge work resisted measurement.
A passage with no location. Still a quotation, still marked as one — but
atis worth filling, because Rule 8 is open the original for the passages that matter and a page number is what makes that a two-second job.
<Margin>
Section titled “<Margin>”label is optional. Floats into the outer margin above 1200px and collapses inline below.
Never load-bearing — resize this window to check that the argument survives it moving.
Ordinary body text continues here so the margin has something to sit beside. At a wide viewport the two notes above are out in the gutter; below 1200px they are inline blocks in this column, in the order they were written. Neither state may overlap this text, and no width between the two may clip either one.
The dialogue exchange
Section titled “The dialogue exchange”## Dialogue has five ### since 2026-09-14, and the fourth, ### How the exchange went, is a
sequence of turns. The label is the syntax. A paragraph that begins **Me:**, **AI:** or
**AI (as sceptic):** starts a turn, and every paragraph or list after it belongs to that turn until
the next label. context/md-spec.md §5c.
How the exchange went
Section titled “How the exchange went”Me: I think the shutdown ritual only works if the day already has an end. Mine often does not.
AI: That objection is fair to the example in the chapter, which assumes a fixed finishing time. The mechanism the chapter names is different, though: it is about closing open loops, not about ending the day. Two things follow from that:
- the ritual can run at whatever hour the work actually stops;
- what it needs is a written list of what is still open, not a clock.
Me: Then the real test is whether writing the loops down works at 23:00 as well as it does at 17:30.
AI (as sceptic): It may not. Late at night the list gets shorter because you are tired, not because less is open — so a ritual that seems to work at 23:00 might be measuring fatigue rather than closure.
Without JavaScript these read as labelled paragraphs. With it, each turn is drawn as one side of the conversation: the accent rule for his turns, the neutral rule for the model’s, and one continuous rule down each turn however many paragraphs it runs to.
Callouts
Section titled “Callouts”Both spellings produce the same element. The directive form is easier to type; the component form
takes a title.
Grouped boxes
Section titled “Grouped boxes”A second card
Cards take an optional icon from Starlight’s own set. No icon dependency is added.
Staggered
<CardGrid stagger> offsets the second column. Use it for two things being compared, never
for a sequence.
Against this
The stagger is decorative and disappears on narrow screens.
Link cards
Section titled “Link cards”Deep WorkRoot-absolute, as every internal link must be. A relative ../ chain is a hard build error.
The shelfCross-links to books and chapters use this. Every path is in src/generated/book-slugs.md.
For one thing seen three ways — never for sequential steps. syncKey makes every tab group on
the page switch together.
Depth of work is a trainable capacity, and the fragmentation is the whole problem.
The prescription assumes autonomy over your calendar, which most of the workforce does not have. The advice is real; its audience is narrower than the book admits.
The mechanism, not the schedule. Protect the two hours I can control and stop treating the other six as a failure.
Sequential procedures only. Blank lines between items are required, or the Markdown inside them is not parsed.
-
Read the chapter. Book only, no AI, no notes.
-
Close it and write
## Recallfrom memory. Ten minutes, badly is fine. -
Only then open the explanation layer.
-
Write the action yourself, and name the obstacle.
Badges
Section titled “Badges”A fenced block, which is what a chapter will almost always want:
actions: - id: dw-02-timeblock if: "it is 21:30 on a workday" then: "I write tomorrow's three blocks in the notebook" obstacle: "I tell myself I will remember it in the morning" tier: now committed: true// Bare < and { are SYNTAX in MDX, not text.if (a < b) { console.log('this line is only safe inside a fence'); }And <Code />, for when the source is a variable rather than literal text:
const measure = cpl * advance * size + gutter;Every fence carries a language tag. Untagged fences lose highlighting silently.
Diagrams — the nineteen declared types
Section titled “Diagrams — the nineteen declared types”Mermaid, in a fenced block. Never hard-code a colour: these re-theme across all four reading
themes automatically, and a literal hex will be wrong in three of them. Toggle the theme with the
Aa control while this page is open — every diagram below must follow it.
Every diagram sits inside the reading column. One wider than the column keeps its size and scrolls inside its own frame. A chart that carries numbers says in its title where they come from — on this page, that they are illustrative. In a chapter they are sourced, or the chart is not drawn.
mindmap — a chapter concept map
Section titled “mindmap — a chapter concept map”mindmap
root((Deep work))
Scarcity
Fragmentation is default
Tools are free, attention is not
Value
Learn hard things fast
Produce at an elite level
Practice
Ritual
Boredom tolerance
Shutdown
flowchart TD — a process or causal chain
Section titled “flowchart TD — a process or causal chain”flowchart TD
A[Read the chapter] --> B{Familiar material?}
B -- No --> C[Clarified chapter]
B -- Yes --> D[Straight to Recall]
C --> E[Recall, closed book]
D --> E
E --> F[Explanation layer]
F --> G[Dialogue]
G --> H{One action worth committing?}
H -- Yes --> I[Name the obstacle]
H -- No --> J[Extract, do not commit]
graph LR — non-hierarchical relationships
Section titled “graph LR — non-hierarchical relationships”graph LR R[Retrieval] --- S[Spacing] S --- C[Cadence] C --- H[Habit] H --- R F[Fluency] -.misleads.-> J[Judgment of learning] J -.suppresses.-> R
timeline — an arc
Section titled “timeline — an arc”timeline title The review schedule, absolute from the start date Day 0 : Action committed : Obstacle named Day 3 : First retrieval : Answer before opening Week 2 : Still running? Week 6 : Keep, adapt or drop Month 3 : Verdict
quadrantChart — a two-axis comparison
Section titled “quadrantChart — a two-axis comparison”quadrantChart title Where a book earns its hours x-axis "Low novelty" --> "High novelty" y-axis "Low actionability" --> "High actionability" quadrant-1 "Read it properly" quadrant-2 "Skim for the procedure" quadrant-3 "Skip" quadrant-4 "Reference" "Deep Work": [0.55, 0.78] "Atomic Habits": [0.30, 0.86] "Meditations": [0.72, 0.35] "The Almanack": [0.44, 0.28]
journey — a sequence with a felt quality
Section titled “journey — a sequence with a felt quality”journey
title One chapter, honestly
section Alone
Read it: 4: Me
Close the book: 2: Me
Write the recall: 1: Me
section With the AI
Read the explanation: 5: Me
Argue with it: 3: Me
section After
Write the action: 2: Me
flowchart LR — a causal chain read left to right
Section titled “flowchart LR — a causal chain read left to right”flowchart LR
T[Trigger fires] --> O{Obstacle present?}
O -- No --> A[Action runs]
O -- Yes --> P[The named plan]
P --> A
A --> R[Day-30 review]
pie — parts of one whole
Section titled “pie — parts of one whole”pie title A week of reading hours (illustrative) "Reading the chapter" : 5 "Explanation layer" : 3 "Dialogue" : 2 "Recall, closed book" : 1.5 "Writing the action" : 0.5
xychart-beta — a bar chart
Section titled “xychart-beta — a bar chart”xychart-beta title "Effect size by study technique (illustrative numbers)" x-axis ["Rereading", "Highlighting", "Summarising", "Self-testing", "Spaced tests"] y-axis "Effect size (d)" 0 --> 1 bar [0.10, 0.15, 0.35, 0.60, 0.75]
xychart-beta — a line chart
Section titled “xychart-beta — a line chart”xychart-beta title "Share recalled after each review (illustrative numbers)" x-axis "Day" [0, 3, 14, 42, 90] y-axis "Recalled (%)" 0 --> 100 line [100, 62, 71, 80, 86]
xychart-beta — bars and a line on one axis
Section titled “xychart-beta — bars and a line on one axis”xychart-beta title "Chapters planned and finished (illustrative numbers)" x-axis [Jan, Feb, Mar, Apr, May, Jun] y-axis "Chapters" 0 --> 12 bar "Planned" [8, 8, 10, 6, 8, 10] line "Finished" [5, 7, 4, 6, 7, 9]
xychart-beta — a histogram, built from bars
Section titled “xychart-beta — a histogram, built from bars”xychart-beta title "Length of reading sittings (illustrative numbers)" x-axis "Minutes" ["0-15", "15-30", "30-45", "45-60", "60-75", "75-90"] y-axis "Sittings" 0 --> 20 bar [3, 9, 17, 12, 5, 2]
sankey-beta — where a quantity went
Section titled “sankey-beta — where a quantity went”What happened to 40 extracted ideas — illustrative numbers. A sankey draws no title, so the caveat lives in the sentence above it.
sankey-beta Extracted,Acted on,7 Extracted,Noted only,33 Acted on,Running at day 30,3 Acted on,Dropped,4
radar-beta — several criteria at once
Section titled “radar-beta — several criteria at once”radar-beta
title Two books on five criteria (illustrative scores)
axis ev["Evidence"], act["Actionability"], nov["Novelty"], cla["Clarity"], dur["Durability"]
curve dw["Deep Work"]{3, 5, 3, 4, 4}
curve mis["Make It Stick"]{5, 4, 3, 4, 5}
max 5
min 0
treemap-beta — a whole, nested
Section titled “treemap-beta — a whole, nested”treemap-beta
title Reading hours by book (illustrative numbers)
"Self-Command"
"Deep Work": 14
"Atomic Habits": 9
"Indistractable": 6
"Learning"
"Make It Stick": 11
"Ultralearning": 7
venn-beta — where ideas overlap
Section titled “venn-beta — where ideas overlap”venn-beta title What three books share (illustrative) set DW["Deep Work"] set AH["Atomic Habits"] set MS["Make It Stick"] union DW,AH["Cues"] union AH,MS["Spacing"] union DW,MS["Effort"]
ishikawa-beta — why something failed
Section titled “ishikawa-beta — why something failed”ishikawa-beta
The 21:30 planning habit stopped
Trigger
Evenings had no fixed end
Phone was in the room
Obstacle
Told myself I would remember
Environment
Notebook lived in the bag
Payoff
Nothing visible by week two
cynefin-beta — what kind of problem the advice is for
Section titled “cynefin-beta — what kind of problem the advice is for”cynefin-beta
title Which kind of problem is this advice for
complex
"Changing a long-standing habit"
complicated
"Designing a review schedule"
clear
"Setting a phone timer"
chaotic
"A week with no control of the calendar"
confusion
"Not yet sure which it is"
chaotic --> complex : "stabilise, then probe"
sequenceDiagram — a dialogue, question first
Section titled “sequenceDiagram — a dialogue, question first”sequenceDiagram
participant R as Reader
participant A as AI
participant B as Book
R->>A: Recall, written closed-book
A->>R: A question, with no position stated
R->>A: My answer
A->>B: Check the claim against the text
B-->>A: The passage and its page
alt The answer matches the book
A->>R: Ask what would change your mind
else It does not
A->>R: Where my answer and the book differ
end
Note over R,A: The position comes after the question
R->>R: Write one action and its obstacle
stateDiagram-v2 — the life of an action
Section titled “stateDiagram-v2 — the life of an action”stateDiagram-v2 [*] --> Extracted Extracted --> Committed: one per book Extracted --> Noted: not now Committed --> Running: trigger fires Running --> Kept: still running at day 30 Running --> Adapted: obstacle changed Running --> Dropped: stopped Adapted --> Running Kept --> [*] Dropped --> [*]
gantt — a book across weeks
Section titled “gantt — a book across weeks”gantt
title One book, chapter by chapter (illustrative dates)
dateFormat YYYY-MM-DD
axisFormat %d %b
tickInterval 1week
todayMarker off
section Part One
Ch 1 read and recalled :done, c1, 2026-09-01, 3d
Ch 2 read and recalled :done, c2, after c1, 4d
section Part Two
Ch 3 read and recalled :active, c3, after c2, 5d
Ch 4 read and recalled :c4, after c3, 4d
section Review
Day-30 review :milestone, m1, 2026-10-01, 0d
block-beta — an argument’s structure
Section titled “block-beta — an argument’s structure”block-beta columns 3 claim["Deep work is valuable"]:3 p1["Learn hard things fast"] p2["Produce at an elite level"] p3["Both need focus"]
A diagram that restates the paragraph above it has not earned its place. Show relationships, not a list of nouns.
What Markdown gives you free
Section titled “What Markdown gives you free”Ordinary bold, italic, inline code, strikethrough, and a root-absolute
link. True quotation marks and dashes come from the typography layer — “like this” — and
ligatures are on in the serif.
A blockquote. Used for a line of the book that is being discussed rather than quoted for its own sake — when it is the latter,
<Passage>is the element, because provenance is the difference.
| Column | What it holds | Rule |
|---|---|---|
| GFM tables | Anything tabular | Wide ones scroll inside their own container |
| Footnotes | An aside that would break the sentence | Renders at the foot with a backlink1 |
| Task lists | A checklist that is not an action | Actions are frontmatter, never a checkbox |
- A completed task-list item
- An incomplete one
- Nested lists:
- work to any depth
- and keep their spacing
- Ordered lists
- Renumber themselves
- Even when you get the source wrong
Headings are anchors, and anchors are contracts
Section titled “Headings are anchors, and anchors are contracts”Every heading on this page has an anchor you can link to. That is why paraphrasing one of the twelve chapter headings is a defect rather than a style choice: it breaks every inbound link, the review loop, and search, and it does all three silently.
In a chapter, an #### means the chapter should have been split, which is a book.json
amendment rather than a heading choice. Here it just proves the level renders.
What is not available — the triage
Section titled “What is not available — the triage”All the judgment is in this table. The inventory below it is neutral and long, and you should not need it. Three verdicts, and the difference between them is the whole point:
| Verdict | Means |
|---|---|
| BREAKS | It fails the build. Loud, immediate, and there is a substitute |
| REFUSED | It would work, and it is not here because it would undermine the mechanism — not because it costs too much |
| DEFERRED | Merely nicer. Logged, opened in a quarterly pass, and untouched until then |
BREAKS — it fails the build, and here is the substitute
Section titled “BREAKS — it fails the build, and here is the substitute”| Wanted | Reality | Instead |
|---|---|---|
Maths, $$…$$ |
Not enabled. The braces parse as MDX and hard-fail | A fenced block, or an image |
An HTML comment <!-- --> |
A parse error in MDX | {/* … */}, and never containing a literal */ |
| A fifth custom component | Expected component X to be defined: you likely forgot to import, pass, or provide it. |
Say it in one sentence. A fifth requires an explicit written request in the session that needs it |
| A second diagram tool | Mermaid is the ceiling | One of the nineteen types above |
a <b in prose |
Unexpected character after a less-than sign, expected a valid JSX tag — and a < b with spaces is fine, which is why this one is confusing |
Backticks. Correct either way |
{threshold} in prose |
ReferenceError: threshold is not defined — a runtime error, so a draft page never reaches it |
Backticks |
A relative link ../foo |
relative link — a hard error, never resolved |
Root-absolute. Paths are in src/generated/book-slugs.md |
A link to a draft: true page |
It has no URL in build |
Plain text until it is published |
#anchor that does not exist on the target |
invalid hash |
Paraphrasing a ## heading breaks every inbound link at once. Do not |
| Emoji in a heading | Breaks anchors, pollutes the search index | Put it in the body, or nowhere |
An image in public/ |
Builds, and silently costs ~88% of the bytes, the hashed filename, the dimensions and the year-long cache | ./name.png, beside the chapter |
REFUSED — it would work, and that is the problem
Section titled “REFUSED — it would work, and that is the problem”These are the ones worth reading. Every one is technically easy, several are the obvious next feature, and each would quietly break something this system exists to protect.
| Wanted | Why it is refused |
|---|---|
| “Chat with my library” — ask a question across every chapter | Letting AI do the retrieval is the crutch effect. Retrieval scored 61% against 40% for rereading, and the entire reconciliation exists to keep the retrieval on his side of the line. A search box that answers is a search box that reads for you |
| Auto-generated “key takeaways” on each chapter | It is ## Recall with the work removed. The page would then contain a better-written version of the one section he is supposed to produce closed-book, immediately above it |
| A reading streak | The evidence wants a person and a physical record, and this site can supply neither. A streak simulates accountability, which is worse than admitting there is none — and a missed day would read as a broken streak, which is exactly how a schedule gets abandoned in week three |
| A “books finished” counter, or a completion percentage | “The ledger is the metric. The count is vanity.” A percentage also puts a completion instinct onto reference and lifelong books, where finishing is not the goal |
| Anything that asks him to picture the outcome — a “visualise your progress” panel, a projected finish date | The strongest negative finding in the evidence base. Positive fantasy predicts LOWER attainment. Nothing on this site may contradict it, and this is where a well-meaning progress widget would land |
| AI-written actions or obstacles | P0’s one rule. An excellent commitment the model wrote produces the feeling of being finished and no change in behaviour |
| Within-chapter pagination | Breaks search, anchors, diagrams and code blocks. The page turn between chapters gives the same feeling at the moment that actually means something |
| Reading analytics beyond the local session timer | The timer is local, never leaves the browser, shows no target and has no streak. That is the ceiling, and it is a ceiling rather than a starting point |
| A rate table converting words to reading minutes | He rejected the premise. “if a chapter is 10 hour or unlimited long, you do it.” A per-section budget would import a constraint he explicitly declined |
| Deciding what transfers to his life | “you don’t remove, alter the things that author wanted to say for original intent, you can give extra instead.” The section may describe where conditions differ; the conclusion is his |
DEFERRED — merely nicer, and not now
Section titled “DEFERRED — merely nicer, and not now”Logged rather than built, because the design system is frozen and the drafts name building the site as “the most sophisticated procrastination available to me.” Opened in a quarterly pass.
| Wanted | Note |
|---|---|
Opened 2026-09-14 on his instruction — “Mermaid used to its full capacity”. The types that render legibly in all four themes are in the diagram section above and in context/md-spec.md §6 |
|
| Per-book accent colour | Would break the tier legend, which is an identity across four themes |
| A dark-mode-only illustration variant | Nothing needs it yet |
| Footnote-style margin notes with automatic numbering | <Margin> already floats above 1200px and collapses inline below |
| Export a chapter to PDF | The browser does it, and custom.css already carries a print block |
The full inventory — neutral, and you should not need it
Section titled “The full inventory — neutral, and you should not need it”Everything on this page, in one list, with no judgment attached. If something is not here, it does not exist for a chapter.
Custom (four, and there is no fifth): <Recall> · <Actions /> · <Passage> · <Margin>
Stock Starlight (seven): <Aside> — four types · <Tabs> / <TabItem> · <Steps> ·
<Card> / <CardGrid> · <LinkCard> · <Badge> · <Code>
Mermaid (nineteen): mindmap · flowchart TD · flowchart LR · graph LR · timeline ·
quadrantChart · journey · pie · xychart-beta · sankey-beta · radar-beta · treemap-beta ·
venn-beta · ishikawa-beta · cynefin-beta · sequenceDiagram · stateDiagram-v2 · gantt ·
block-beta
Chrome, with no markup: comments on any passage · Expand on every diagram · dialogue turns from
their labels · the book’s release dates from book.json
Markdown, free: headings and anchors · GFM tables · footnotes · task lists · ordered, unordered and nested lists · blockquotes · inline bold, italic, strikethrough and code · fenced code with a language tag · horizontal rules · links
From the build, free: full-text search · four reading themes with a toggle · breadcrumbs ·
prev/next scoped to the book · build-time link validation · “Last updated” from read: ·
a .md sibling for every page · llms-full.txt
Composition rules are in /method/ and context/md-spec.md §5b. The one that catches everyone:
blank lines are required around a component’s inner content, or the Markdown inside is not
parsed as Markdown — and it renders, just wrongly.
Open questions
Section titled “Open questions”Left empty on purpose, even here. On a chapter page this is the prohibition zone: the AI never writes in it, because the questions you could not answer are the highest-value note anyone keeps and the ones nobody records.
Sources
Section titled “Sources”context/md-spec.md§3 and §5 — the authoring contract this page is the rendering of. That file is the source; this page is the proof. If they disagree,md-specis right and this page has rotted.context/chapter-spine.md§1 — the twelve headings, and why this page is exempt from them.context/source-rules.md— what a citation must be, which is a different question from whether one exists.
Footnotes
Section titled “Footnotes”-
The footnote. Both directions of the link are generated, and both are anchors, so both are contracts — renaming a heading breaks inbound links the same way. ↩