Trackers

A fenced block that turns a note into a living progress card — and a board that shelves all of them.

A tracker keeps count of how far you are through something: a book, a game, a course, a project. You write it as a ```tracker fence (a code block whose language is tracker) inside any note, and it renders as a card with cover art, a progress bar, a status chip, a rating and your own notes. The card looks the same in the editor, in the reading view, on the published blog, and inside a transclusion, because all four draw it with the same renderer.

title: Elden Ring
kind: game
cover: elden-ring.jpg
progress: 62/130
unit: hours
status: playing
rating: 9/10
started: 2026-07-01
notes: |
  Margit took 14 tries.

The fields

Unknown keys are ignored. A fence with neither a title nor a progress stays a plain code block. That is deliberate: content that cannot be parsed should read as its own source rather than vanish into an empty card, which is the rule $$ math $$ already follows.

A note may hold as many trackers as you like.

Reading sessions

When you close a book in the book reader, the sitting is written into the book's tracker as one line of a sessions: block:

title: Muqaddimah
kind: book
progress: 139/500
file: Books/Muqaddimah.pdf
sessions: |
  2026-09-14 | 100–112 | 12 pages | 20 min
  2026-09-15 | 112–139 | 27 pages | 41 min

Reading left to right, separated by |: the date, the first and last page of the sitting, the pages finished, and the minutes the clock counted. The line is yours as much as the app's: write one by hand and it counts; delete one and it never happened. The pieces may come in any order and in either language (٢٧ صفحة | ٤١ د), the range may be missing, and a line that does not open with a date is not a session. When the tracker counts pages, the progress: line moves by the pages read at the same time.

From the last five timed sittings the card reads the book's own speed and says about 1.6 pages a minute here — 4 h 20 left, under the pace projection when there is one. The weekly review adds the lines up by book.

Sittings from progress

Not every book passes through the reader. When a book's progress: moves forward (a press of + on the Media page or on the card, a new number typed into the fence, a note that arrives from a sync) and nothing in the same save accounts for the move, Astrolabe writes the sitting itself, dated the day it saw the move:

  2026-09-27 | 139–160 | 21 pages | ~32 min
  2026-09-27 | 3–5 | 2 chapters | ~60 min | default pace

The ~ says the minutes are estimated, not timed. They come from your own pace first: the minutes a page (or a chapter, or whatever the book counts) over this book's last five timed sittings; when it has none, over every timed book sitting in the vault in the same unit; when there are none either, the defaults, which are 1.5 minutes a page, 30 a chapter, 10 a section, 120 a part or volume, an hour an hour, and 10 minutes for any other unit. A book kept in chapters whose PDF the reader has opened spreads its pages over its chapters instead: 300 pages in 12 chapters is 25 pages a chapter, at your page pace or the default one. A line whose estimate rests on the defaults ends | default pace, and the calendar's day pane says estimated under it; one from your own pace says estimated from your pace.

The rules, so that a line is never a surprise:

• Only books count: a tracker of kind: book (or a word that folds into it, such as novel), or a fence with no kind that counts pages. A game's hours are not a sitting.
• A tracker met for the first time gets nothing. Astrolabe remembers the progress it last saw for each one in trackers-progress.json in the data folder, so a restart counts nothing twice; lose that file and every book is simply met again.
• Several moves on one day are one line: the range grows, the pages add up, and the time is estimated again for the whole.
• A move back writes nothing new; it takes back what that day's line had counted, and the line goes when nothing is left of it. A number typed on its way (62, then 6, then 70) counts from 62.
• A save that brings its own sitting, the reader's or a line you typed with the new number, is left alone.
• A timed sitting is never touched, and a line you have edited or deleted is yours: Astrolabe only ever rewrites the line it wrote, word for word, and never puts back one you removed.
• sittings: manual in the fence turns all of this off for that book.
• The day is the instance's own. A move made in the phone app's offline pocket is written when it reaches this instance, on the day it arrives.

An estimated sitting is a sitting everywhere else too. The calendar lists the book under that day (in the month's cell in muted ink, when the bar is all the day knows of it), the Timeline and the weekly review print its time with the ~, and the year in review counts it and says how many sittings and minutes were estimated. Only the card's reading speed leaves it out, because it is that speed read back.

Nudging the bar

In the editor, an admin session gets a quiet − and + at the card's inline edge. One press is one unit: it rewrites the progress: line in your file and nothing else, as a single undo step. There is no separate store. The note is the state, so editing the number by hand does exactly what the button does.

Cross 100% and the bar takes on a soft glow, and Astrolabe's own ✦ appears beside the count.

The reading view and the public site are inert by design: there is no write path for a visitor, and buttons that cannot work are furniture that lies.

The board

A ```tracker-board fence draws every tracker in the vault as a grid of mini-cards, grouped by status (active first, then planned, done, paused, dropped). Each card links to the note its tracker lives in.

kind: game
status: active
limit: 12

An empty body is a board of everything. A vault with no trackers gets an inviting empty state rather than a blank.

Publishing a shelf

The board knows who is looking. It reads GET /api/trackers, which answers each viewer with what they are allowed to see, by the same rule as the blog's own post list:

• a visitor sees trackers from published notes only, with the same language filter the blog applies;
• an admin sees the whole vault;
• templates are excluded from both: a template carrying a tracker skeleton would otherwise shelve itself as a book nobody has started.

So a board left on a published note is safe: you can put your reading year on the public site without opening the rest of the vault. Cover art on a published tracker is served to visitors too; the indexer adds tracker covers to the same list of files a visitor may fetch, beside banners and embeds.

The Media page

The board is a fence you put in a note. The Media page is the same shelf as a place of its own. A button beside the settings gear (admins only; or "Open the Media page" in the command palette) opens it as a tab in the focused pane, beside the notes, holding every tracker in the vault shelved by kind. The same button closes it again, and it drags into a split like any tab.

The shelves stack vertically with a hairline between them, in this order: shows, games, books, films, courses, then projects, habits and whatever kinds of your own you have invented. Each shelf is a grid of at most five works across, fewer as the window narrows, and the page scrolls down and never sideways. A row of filters at the top narrows every shelf to one status.

Each card is the fence's card in miniature: cover, title, bar, count, status, rating, dates and the first lines of your notes. Its − / + nudge the progress exactly as the editor's stepper does, Edit reopens the form filled in, Delete sends the work's note to the trash through the same dialog the tree uses (Undo on the toast, and the trash browser can bring it back), and the cover or title opens the note.

Add media is a form: kind, title, cover (pick a picture the vault already has, upload one, or paste an https:// link), progress, unit, a season for a show, status, rating, dates and notes. It writes one note:

Media/Shows/Severance.md

whose body is one ```tracker fence with those fields, so everything the rest of this page says applies to it: it renders as a card in the note, it appears on any board, and you can edit the fence by hand. The kind decides the folder (Books, Games, Shows, Films, Courses, and a capitalised folder for a kind of your own). On an Arabic instance the folders are Arabic too: وسائط/كتب, ألعاب, مسلسلات, أفلام, دورات. A vault that already has a Media root keeps filing there, and the reverse holds. A title that already has a note is refused rather than overwritten.

For a game whose length nobody has timed, switch the total off: the fence says progress: 62/?, and the card counts hours and draws no bar. Turn it back on later and the bar returns.

A folder of your own notes. Notes in the vault on the form (or folder: in the fence) points a work at a folder, the one you already keep your chapter notes or episode notes in. The card grows a chip that counts the notes there and opens them: the sidebar opens, the folder unfolds in the tree and pulses three times so you can see where it is, and a folder that has its own note (a note named like the folder, or index.md) opens that note as well; under the chip, the one note you touched last, a door back to where you left off. The right panel keeps the same link from either end: on a note inside the folder, Tracked in names the work, draws its bar and nudges it; on the tracker note itself, Notes of this work counts the notes, shows the last one you touched and opens the folder. In the sidebar the folder wears the work's glyph beside its name, and that mark opens the tracker. Nothing is moved and nothing is written into those notes. When the same folder is a library path, the path's shelf card and page wear this tracker's cover, over any cover the row or the folder note names, so the book you are tracking and the book your readers open are one picture.

Editing from the page rewrites only the fence in the note. The prose under it, the frontmatter and any second tracker stay byte for byte as they were.

The page is admin-only because it writes. A visitor's shelf is the board, on whatever note you chose to publish it.

In Obsidian

tracker is an Astrolabe extension, not an Obsidian feature. Open the same vault in Obsidian and the fence goes back to what it is underneath: a labelled code block whose lines are all readable. Nothing is converted, nothing is lost, and the note still says everything it said here. The same is true of a sigil; a drawing is the Excalidraw plugin's own file; and an orbit writes its schedule in the Spaced Repetition plugin's own format.