Link to section: Add a paperAdd a paper
A paper is one Markdown file inside a collection folder. Save it as content/<collection>/<name>.md, then run npm run build. The file name becomes the address, so my-first-paper.md is published at my-first-paper/.
---
title: "A clear title"
summary: "One or two sentences that appear on the shelf and in search."
subtitle: "Optional"
date: 2026-10-18
updated: 2026-11-02
status: working # draft, working, reviewed or final
tags: [topic, another topic]
after: [other-collection/other-paper]
order: 3
sources:
- label: "Author, Title (Year)"
url: "https://example.org"
kind: primary # primary, secondary or unverified
---
Only title and summary are required. A paper with no status is a draft. Leave updated out and it takes the value of date.
Link to section: Add a collectionAdd a collection
A collection is a folder under content/ with a file called _collection.json.
{
"title": "Collection title",
"summary": "A short line for the shelf.",
"cloth": "madder",
"order": 4
}
The cloth sets the colour of the book and its spine. The choices are indigo, madder, bottle, saffron, aubergine and slate. Files that start with an underscore are skipped.
Link to section: Link between papersLink between papers
Inside a paper, link with @ and the paper's id: [text](@collection/paper). Within the same collection, the bare name works: [text](@paper). Add #heading-id to point at a section. A bad link stops the build and names the file, so a broken reference cannot be published by mistake.
The after field in front matter says "read these first". The library then shows the reverse link, "leads on to", on the earlier paper.
For an example that uses most of the components below, see What the studies on dhikr breathing show.
Link to section: Marks for how sure you areMarks for how sure you are
Three inline marks record the state of a claim, and each one is readable without colour.
==verified== ??unverified?? ~~discarded~~
Rendered: the date was confirmed in two sources (verified in a primary source), the figure could not be traced to its origin (unverified), and the claim was invented (discarded).
Link to section: Footnotes become side notesFootnotes become side notes
Write [^name] in the text and [^name]: the note anywhere below.
A footnote sits in the margin on wide screens and opens on tap on small ones.1This is a side note. It carries no claim.
Link to section: Arabic, Persian and UrduArabic, Persian and Urdu
Inline text uses {ar:…}, {fa:…} or {ur:…}, which set the direction and the font. For example بسم الله, هوش در دم and پاس انفاس.
A block with a citation line uses a container named ar, fa, ur or rtl.
::: ar Optional citation line
لا إله إلا الله
:::
لا إله إلا الله
The kalima
Link to section: Notes and slipsNotes and slips
Five kinds of slip carry a title and a body: note, verified, unverified, discarded and caution.
Link to section: Diagrams from plain textDiagrams from plain text
All of the data below is synthetic demo data (verified in a primary source) and says nothing about the real world.
Link to section: BreathBreath
::: breath Title of the diagram
Row label | in:first | out:second
Another row | in:one | hold:two | out:three
:::
Link to section: ChainChain
::: chain Title
Name | note | status
:::
The status is optional: verified, unverified, disputed or discarded.
- First link VerifiedPlaceholder
- Second link UnverifiedPlaceholder
- Third link DisputedPlaceholder
Link to section: TimelineTimeline
::: timeline Title
1900 | What happened | Optional note
:::
- The first eventA note on the first event
- The second event
- The third eventA note on the third event
Link to section: BarsBars
::: bars Title
Label | 12 | Optional note
unit: person/people
max: 20
:::
The unit can be a single word, or a singular/plural pair, which is chosen by the value.
Link to section: Register of claimsRegister of claims
::: register Title
The claim | verified | Where it was checked
:::
The status must be verified, unverified, disputed or discarded. The build stops on anything else.
| Claim | Status | Basis |
|---|---|---|
| A claim that holds | Verified | Two sources agree |
| A claim with one source | Unverified | Only one site makes it |
| A claim the sources split on | Disputed | Authors disagree |
| A claim that was rejected | Discarded | The source does not say it |
Link to section: MatrixMatrix
A table whose cells start with yes, no, partial or disputed becomes a matrix. Text after a colon is a note.
::: matrix Title
| Item | Feature |
|---|---|
| One | yes: the note |
:::
| Item | Has the first feature | Has the second feature |
|---|---|---|
| Item one | yes | no |
| Item two | partialonly in part | yes |
| Item three | disputedsources differ | no |
Link to section: FiguresFigures
A figure container holds an image with a caption. Put the image in content/<collection>/assets/ and refer to it with assets/name.png.
::: figure Caption for the figure
:::
Link to section: Search, reading progress and printingSearch, reading progress and printing
Search runs in the browser over every paper, ignores diacritics and Arabic vowel marks, and needs no server. The spine on each paper fills as you read. A paper you have finished reading is remembered on this device only. Printing a paper hides the navigation and keeps the sources.
Link to section: PublishPublish
Pushing to GitHub rebuilds and publishes the site through the workflow in .github/workflows/pages.yml. Set url in site.config.json to the published address first, so the not-found page can find its way back.