[idea:rookery-todos]alpha-package2026-08-20

`@rookery/todos`

Writes todos and epics as ideas with a dependency graph over them, so a rookery can say for itself what is ready to work, what is blocked, and what has gone stale.

A todo is an idea with a priority, a state and a list of the todos it waits on. Nothing computes what to do next, as the graph already knows.

#import "@rookery/core:0.1.0": rookery
#import "@rookery/todos:0.1.0": todo, todos-ready, todo-graph-view
#show: rookery

#let TODAY = datetime(year: 2026, month: 8, day: 25)

/* Name any todo something else depends on. An auto-named #todo[..] takes a
   sequence id that shifts the moment a note is inserted earlier in the file,
   silently repointing every dependency on it. */
#todo("fetch", title: [Fetch the source], priority: 0, done: datetime(year: 2026, month: 8, day: 1))[..]

/* Priorities run the way birds' do, a higher number being more important with
   no ceiling, so escalating something never means renumbering everything
   below it. */
#todo("parse", title: [Parse it], priority: 9, type: "bug", deps: ("fetch",))[..]

/* parse waits on fetch, fetch is closed, so parse is what surfaces here.
   Every view needing a now takes today: explicitly and panics without one. */
#todos-ready(today: TODAY)
#todo-graph-view(today: TODAY)

Grouping todos into an epic

An epic is a tag with a constructor bound to it rather than a container. Two todos in one epic stay unrelated until one names the other in deps:, as the epic groups them without ordering them.

#let launch = epic("launch")
#launch("plan", priority: 5)[Kick-off.]
#launch("post", deps: ("plan",))[Follows the plan.]

Todos

[idea:hatching-ideas]Hatching ideas

Ideas are designed so that you can always hatch new ones without ceremony. The #idea function at its most basic takes the content of an idea.

#idea[Hatch a new idea.]

You can think of an idea as an evergreen note, as an atomic unit of thought, as a generalization of the Orgmode TODO, or simply as a referenceable and taggable block of content. All ideas in your rookery are conceptually networked together so that you can treat a rookery as an associative archive.

An idea might be a short note you want to jot down, a record relating to a person or a place, a blog post, an academic paper, a todo item, a meeting note, a note associated to a citation, a tracking issue for a call for proposals, or any other kind of structured content fragment you can imagine. You can specify custom metadata structures for certain types of ideas using tags.

Reference documentation for #idea.

[idea:ideating]

Ideating

When you sit down at your computer, ready to jot down some ideas or write a piece, it wouldn’t be nice to have to always explicitly wrap your content in #idea blocks. You can use the #ideate function in combination with a Typst #show rule to implicitly parcel your writing into ideas:

#import "@rookery/core:0.1.0": ideate
#show: ideate

= Let's get rolling
Straight into it without ceremony.

This will wrap your writing as an idea, taking the #document.title as its name. Importantly, you can parameterize the #ideate function to parcel your writing out into ideas differently:

#show: ideate.with(separator: heading.where(level: 2))

== First idea
The body of my first idea.

== Second idea
The body of my second idea.

This is useful when you want to take writing in Typst that isn’t structured as ideas and import it into a rookery, as you don’t have to retrofit #idea blocks throughout: you just need to design the right #ideate show rule. Ideation also works nicely with Rheo spines, as it means that you can organize your ideas using files and folders and still have them appear in the flat idea space so that they can be further organized using tags.

Reference documentation for #ideate.

[idea:tags]

Footnotes

A footnote belongs to the idea in which you write it, just as citations do. So that rookery can track them correctly, you need to use the footnote function imported from rookery in ideas, rather than the Typst native function. (Using Typst’s own #footnote will cause a compilation error.)

#import "@rookery/core:0.1.0": idea, footnote
#idea("etal")[
  A claim#footnote[The evidence.] worth qualifying.
]

Footnote numbering is idea-local. This means that there may be two footnotes labeled 1 on the same page, if two ideas with footnotes are hatched in that context.¹

Footnote listings occur at the end of each idea.² On a standalone page, footnotes appear before the context and backlinks listings.

A footnote written outside an idea’s context proxies the native Typst function so that it behaves normally.

What you write inside a footnote belongs to the idea as well, and not to the footnote. A citation in a footnote is claimed by the surrounding idea and listed in its References,³ and a window or an @idea: reference in a footnote registers its backlink exactly as it would in the idea’s own prose.

Footnotes

^ This idea’s own first footnote. The idea below has one too, also numbered 1.
^ Ideas carry their footnotes everywhere they appear in the rookery—their hatching context, their standalone page, and their windows. The only exception to this is where a window on an idea carries a limit which truncates the content.
^ As this one is (Mädje 2022). Look for it in this idea’s References block below, rather than in the footnote itself.

References

Mädje, Laurenz. 2022. “A Programmable Markup Language for Typesetting.” Master's thesis.

[idea:citations]

Citations

A citation belongs to the idea in which you write it, just as footnotes do. Bibliographies, like footnotes, are produced at the end of an idea.

In contrast to footnotes, however, all citations in a rookery draw from a global bibliography that is configured once like so:

#show: rookery.with(bibliography: arguments(
  bytes(read("references.bib")),
  style: "chicago-author-date",
))

You must use bytes(read(...)) rather than a path to pass a reference file, but rookery bibliographies otherwise work the same as Typst bibliographies.

Once a rookery is configured with a bibliography, you can cite as you naturally would in Typst (Mädje 2022). Bibliographies will appear at the bottom of every idea with a citation under a ‘References’ heading.

Citation numbering is rookery-wide, which means that numeric styles will not be scoped to each idea. (An idea with one citation may show it as [7], for example, if it is the 7^th citation in the rookery.) For this reason we recommend using citation styles that don’t employ numbers, such as "author-date".

References

Mädje, Laurenz. 2022. “A Programmable Markup Language for Typesetting.” Master's thesis.

[idea:genealogy]What is the genealogy of idea?

An idea in a rookery can be conceptualized as an atomic note of sorts, which is why each idea is given its own standalone page. As with notes in other Zettelkasten-inspired systems, ideas that link to each other produce backlinks.

In addition to the sense of an idea as a ‘Zettel’ or note, you can also think about them as slightly more general kinds of ‘todo’ item, as in Org-mode TODOs. Indeed, the notion of ideas comes from the IDEA variant in Doom Emacs, a preconfigured cluster of plugins for the Emacs editor.

Rookery ideas are designed with structured extensions in mind. You can structure ideas into todos, meeting notes, or even application tracking pages.

[idea:alpha-packages]The following packages are alpha software, and thus subject ...

The following packages are alpha software, and thus subject to API breakages, bugs, and unlikely behavior. Use them at your own risk!

In order to take this risk, you need to update your Rheo project to use rookery’s dev branch:

[packages.rookery]
repo = "https://github.com/freecomputinglab/rookery"
branch = "dev"

@rookery/bibtex

@rookery/cfps

@rookery/meetings

@rookery/pinboard

@rookery/search

@rookery/slipshow

@rookery/timeline

@rookery/todos

Index