Rookery - Tags

[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:ideating]Ideating

#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.

Reference documentation for #ideate.

[idea:inspiration]What inspired rookery?

Rookery builds on thinking about associative archiving that dates back to 2019. Its name and metaphor system derive from thinking about software in the age of large language models.

More generally as a knowledge management tool, rookery takes its cue from the Zettelkasten method, which was popularized in 2019 by Roam Research, and which has since influenced both Obsidian and Notion, two popular knowledge management platforms.

Of these tools, rookery is closest in spirit to Obsidian in the sense that it allows you to create and manage a local-first knowledge base using plain-text files on disk. Unlike Obsidian, however, rookery is not an editor or IDE, which means you can author the Typst files in it however you like.

Another way of thinking about rookery is that it is a Zettelkasten framework built on Typst that is more structured than Obsidian and Notion, but not so structured that you need to know anything in particular about Zettelkasten in order to use it. Rookery allows you to organize your thinking using ideas and tags in a way that is compatible with Zettelkasten and Zettelkasten-inspired systems like Roam, without enforcing or requiring strictly atomic notes.

In addition to those mentioned above, three ways of thinking about note systems have concretely influenced rookery’s design:

Andy Matuschak’s evergreen notes.
Jon Sterling’s intellectual junkyards.
Emacs’ Org-mode.

[idea:genealogy]faq

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:other-tools]faq

What are other tools like rookery?

Rookery was inspired by a range of existing knowledge management tools.

[idea:forester-rookery]faq

Forester | Rookery

Forester is the open source system most similar to rookery, and also its chief inspiration. Forester is an OCaml engine that Jon Sterling develops to power his website. It is not wrong to think about rookery as forester reimplemented for and in Typst.

Both rookery and forester have:

Atomic notes with unique and stable names (ideas and trees, respectively)
Bidirectional linking and transclusion, which is a fancy word meaning that you can embed one note in another as a window.
Compilation to a standalone static site.

The core differences between forester and rookery:

Forester rolls its own enhanced markup language, whereas rookery uses Typst. This has consequences for how hyperlinks, mathematical markup, footnotes, citations, and inline code blocks are specified.
Forester requires an OPAM/OCaml toolchain and has a datalog-based query engine, whereas rookery is written in pure Typst.¹ Both produce standalone static sites.
Rookery can be incrementally adopted in an existing Rheo project—a ‘normal’ writing project or website that isn’t organized as atomic notes—by sprinkling #idea blocks in as they are conceived, whereas forester must be adopted wholesale.
In addition to HTML and PDF, rookery can export to EPUB.
Rookery allows you to give ideas human-readable, semantic names if you prefer not to accept the names it derives automatically.
Forester was first released in 2023 and its latest major version, 5.0, was released in July 2025. Rookery is pre-release software (version 0.x) that was announced in September 2026.

Footnotes

^ We recommend compiling rookeries with Rheo for a better experience, but it is not strictly required.

[idea:kodama-rookery]faq

Kodama | Rookery

Kodama is another forester-inspired tool for authoring intellectual junkyards in Typst.

Rookery produces HTML, PDF, and/or EPUB, whereas Kodama renders only HTML.
Kodama does not explicitly support transclusion with windows, idea-scoped footnotes or citations, tags to organize ideas, mobile viewing, or standalone pages for each idea.
Kodama requires a separate binary to compile in addition to Typst, whereas rookery needs only the Typst toolchain (or Rheo as the preferred interface to it).
Kodama allows you to write your notes in either Markdown or Typst, whereas rookery is pure Typst.

[idea:rookery]A rookery

A rookery is a place where your ideas can grow. Rookeries are collections of files, entirely local and owned by you, with no vendor or cloud lock-in. When rookeries are compiled with Rheo, every idea can be rendered as a webpage, a PDF, or an EPUB, at any time. This is true also for collections of ideas, ranging from a set of ideas with the same tags to your entire rookery.

One use case for rookery is searchable documentation sites, just like this site, which is (yep, you betcha!) itself a rookery. It can also be used as a Typst alternative for an organization site, a blog, or a research journal. More generally, rookery allows you to structure content in such a way that it is interlinked, easy to grow over time, and capable of being viewed in multiple different orders. It thus also makes a good basis for context engineering workflows and LLM-assisted development.

Getting started

[idea:idea]concept

An idea

An idea in a rookery is written in Typst. Every idea can be referenced by any other idea or page in the same rookery.

Each idea also gets a standalone page that will show its context—where it was first hatched—and its backlinks—the set of other ideas and pages that reference it—in its footer. Try clicking on this idea’s name above (the [idea:idea] text), to see its standalone page as an example.

Ideas can be hyperlinked to other ideas, or they can be interpolated as windows onto the original idea. Clicking on the title of a window will unfold the idea within your current context. Clicking on the idea’s name will take you to the idea’s standalone page.

Try unfolding these windows below by clicking on their title panel to learn more.

Hatching ideas

Referencing ideas

[idea:idea-reference]#idea

For an intuition on how to think about ideas, see An idea. The #idea function takes the following arguments, which are all optional:

Argument	Type	Description
`name`	label \| str	A unique name for the idea, allowing it to be referenced as `@idea:<name>` across the rookery. Positional, and written either as a label or as a string—`#idea(<etal>)` and `#idea("etal")` are the same call. In the absence of an explicit name, an idea with a `title` takes a slug of it; an idea with no usable title instead takes a slug of its own body plus a content digest, as described under auto-naming.
`title`	content	The idea’s title, which appears as both the link text in hyperlinks to the idea and the header text in windows on it.
`body`	content	The idea’s content, rendered inside its card and transcluded by any window on it. An idea with no body is a title-only stub, which is how a placeholder for an idea not yet written is filed.
`level`	int	The heading depth of the idea’s title, so a nested idea can sit under the one containing it. Defaults to `1`.
`tags`	str \| array \| dictionary	The idea’s tags, as one name, a list of names, or a dictionary whose values carry arbitrary metadata for the tag. Set at the call site, replacing whatever a constructor bound.
`tag`	str	A single tag that is merged into `tags` rather than replacing it, so a constructor such as `idea.with(tag: "note")` keeps its tag when the call site names tags of its own.
`base-tags`	str \| array \| dictionary	As `tag`, but for several tags at once — for a family of ideas that is a narrowing of a broader one, so that every idea the constructor mints is still reachable under the wider tag.
`exclude-tags`	str \| array	Tags that drop the idea from this build entirely. An excluded idea is absent rather than hidden: nothing renders where it was written, no page is minted for it, and it appears in no outline, search index or backlink list.
`created`	datetime	The date the idea was written. In its absence the containing document’s own `#set document(date: ..)` is used; a date is otherwise never invented.
`display`	dictionary	What the idea shows of itself, as a dictionary of nine flags — see below.

Every display key takes a boolean, and defaults to auto: the rookery-wide setting given to #rookery(display: ..). An idea states an opinion only where it differs from the rest of the rookery.

#idea(
  display: (
    // the idea's own minted page carries its title as an `<h1>`
    title: true,
    // the `created` date sits at the right-hand end of the hat
    date: true,
    // the tags are worn in the hat as pills, metadata tags excepted
    tags: true,
    // the idea is drawn as a card, with its left rule and indent
    frame: false,
    // the name is shown in the hat as a permalink
    name: true,
    // the minted page footer links back to the page written on
    context: true,
    // the minted page footer lists everything that links here
    backlinks: true,
    // unused by the card itself — seeds what a later window on
    // this idea falls back to when it does not override them
    label: true,
    background: true,
  ),
)[..]

Each key is also an argument in its own right, with the prefix restored — display-frame: false — and an argument on the same call wins over the dictionary’s value for that key.

Everything else spelled idea- reads one back out, and is nested here: its tags, where its page sits, its body, and the row that stands for it in a list.

[idea:idea-tag-names-reference]reference

`#idea-tag-names`

One idea’s tag names, as a flat array.

#import "@rookery/core:0.1.0": idea, idea-tag-names

#idea("etal", title: [Et al.], tags: (note: none, draft: none, priority: 1))[
  Attribution flattens a crowd into one name.
]

#context idea-tag-names("etal")   // -> ("note", "draft", "priority")

Every key, valued tags included — priority comes back alongside the two plain tags, because a tag carrying metadata is still a tag. This is the question of what an idea is tagged, not of what those tags hold. Key order is unspecified.

() comes back both for an untagged idea and for a name that does not exist. A missing idea is not an error here: a caller asking what something is tagged is filtering, not dereferencing. Must be called inside #context.

Where you are walking the whole rookery, read the tags field off #ideas instead: this resolves the registry once per idea, where #ideas resolves it once for the pass.

[idea:idea-tag-value-reference]reference

`#idea-tag-value`

One tag’s value on one idea.

#import "@rookery/core:0.1.0": idea, idea-tag-value

#idea("etal", title: [Et al.], tags: (note: none, priority: 1))[
  Attribution flattens a crowd into one name.
]

#context {
  idea-tag-value("etal", "priority")            // -> 1
  idea-tag-value("etal", "note")                // -> none, a plain tag
  idea-tag-value("etal", "nope", default: 4)    // -> 4
}

Takes the same name forms as #idea-tag-names, and returns default where the idea does not exist or carries no such key.

A plain tag’s value is none, which is indistinguishable from a default of none on a key that is absent. This function answers what a tag is set to, and a plain tag is set to nothing; ask #idea-tag-names or #tag-data when the question is presence. Must be called inside #context.

[idea:idea-href-reference]reference

`#idea-href`

Where an idea’s minted page sits, relative to the page you are calling from. Takes a bare name, a full name or a label — the same forms #window and #hyperlink take — and must be called inside #context.

#import "@rookery/core:0.1.0": idea, idea-href

#idea("etal", title: [Et al.])[
  Attribution flattens a crowd into one name.
]

#context idea-href("etal")
// -> "ideas/etal.html"    called from a root page
// -> "../ideas/etal.html" called from a page one directory down

The depth arithmetic is measured from the calling page, so the same idea yields a different string on a nested page than on the root one. That is the point of the function, and it is why a caller must never cache the answer across pages.

none wherever no page is minted: a plain typst compile with no Rheo, and the combined PDF target.

[idea:idea-path-reference]reference

`#idea-path`

The same page as #idea-href, from the site root rather than from here.

#import "@rookery/core:0.1.0": idea, idea-path

#idea("etal", title: [Et al.])[
  Attribution flattens a crowd into one name.
]

#context idea-path("etal")
// -> "ideas/etal.html", from either page above

Reach for it where the caller has no page of its own to measure depth from — a feed configuration or a sitemap invoked once from shared code rather than from a page. It is none under the same two conditions #idea-href is.

[idea:idea-body-reference]reference

`#idea-body`

One idea’s body, rendered, with none of a window’s chrome: no summary line, no permalink, no disclosure. For a consumer that wants to show an idea rather than describe it — a preview pane, a card in a view of the caller’s own design — where #ideas’ body field only hands over plain text.

#import "@rookery/core:0.1.0": idea, idea-body

#idea("etal", title: [Et al.])[
  Attribution flattens a crowd into one name.

  The convention is older than the citation styles that inherited it.
]

// anywhere after it, on any page
#idea-body("etal")            // both paragraphs, no title, no permalink
#idea-body("etal", limit: 1)  // the first paragraph alone

Argument	Type	Description
`name`	str \| label	The idea to render, in the same name forms every accessor here takes.
`unfurl`	int \| auto	The transclusion budget, as on `#window`. Pinned at `1` rather than auto, so a preview’s size stays bounded however deeply the idea it shows nests. `0` asks for no unfurling and still renders the body — there is no chrome here to fall back to a link.
`limit`	int \| none	How many blocks of the body to show, the same unit `#window`’s own `limit` cuts by. The whole body by default.

It supplies its own #context, unlike the data accessors on this page, so it can be called anywhere. The body comes wrapped in the same classes a window’s does, minus the box, so every rule the stylesheet already writes for prose inside a window — link colors, code, lists, footnotes — applies with nothing for a consumer to restyle.

[idea:idea-row-reference]reference

`#idea-row`

One row of a list of ideas: a date, a title, cells and badges, as an <li>. The shape @rookery/search and @rookery/timeline both draw, kept in core so that a project reaching a row through one of those packages still gets core’s CSS with it.

#import "@rookery/core:0.1.0": idea, ideas, idea-row

#idea(
  "etal",
  title: [Et al.],
  tags: (note: none),
  created: datetime(year: 2026, month: 8, day: 20),
)[Attribution flattens a crowd into one name.]

#context html.elem("ul", ideas(tagged: "note").map(e => idea-row(
  when: e.created.display("[day] [month repr:short]"),
  iso: e.created.display("[year]-[month]-[day]"),
  title: e.label,
  href: e.href,
  tags: e.tags,
  badges: e.tags.map(t => (text: t, tag: t)),
)).join())

The row is fed from #ideas rather than from the idea directly, which is the usual shape: a view selects its ideas, decides what their dates mean, and hands the row cells that are already content.

Argument	Type	Description
`when`	content \| none	The date cell, already formatted. none draws an em dash.
`iso`	str \| none	A machine-readable date, which wraps `when` in a `<time>` element carrying it.
`soft`	bool	Whether this date answers a different question than the list asked — a booked event standing in for a deadline. Dropped silently on a row with no date, which makes no such claim.
`when-class`, `when-attrs`	str \| array, dictionary	Extra classes and attributes on the date cell, for a consumer that bands a deadline by how close it is. Core defines none of these names and styles none of them.
`title`	content	The row’s title.
`href`	str \| none	Where the title links. none renders it as a span instead.
`badges`	array	The chip strip at the end of the row. A `(text: .., tag: ..)` dictionary draws the ordinary chip, wearing the same `.idea-tag-<tag>` class a pill and an outline row do, so a themed tag colors itself; anything else is placed verbatim and the caller owns its markup. An empty strip is omitted rather than drawn empty, since a childless span still takes a grid track.
`cells`	array	Extra content cells between the title and the badges — a host institution, a path — for what a reader scans down a column for rather than reads inside the title.
`tags`	array	Tag names, which become `.idea-tag-<tag>` classes and a `data-rookery-tags` attribute on the `<li>`.
`extra`, `attrs`	array, dictionary	Extra classes and attributes on the `<li>`, merged under the classes this function computes so a caller cannot drop the row’s own. This is what lets `@rookery/search`’s panels hang their `data-panel-*` attributes off a row without re-emitting its markup.

Cells arrive formatted, and that is the whole of the design: the row asks no questions about what a date or a badge means, so one row shape serves a log-derived queue, a filter panel and a hand-built table of submissions, none of which agree about what a date is. It carries no JavaScript — interaction stays in @rookery/search.

HTML only, and deliberately: a paged target has no grid to align and no anchor to click, so every view in this family keeps its own branch that builds a plain list(..) there. Calling it on a paged target fails with a message about the mistake rather than about the element.

[idea:idea-row-body-reference]reference

`#idea-row-body`

The same row, without the <li> around it. It takes every #idea-row argument except the three that describe that wrapper — tags, extra and attrs — and is for a caller that owns the list item itself.

#import "@rookery/core:0.1.0": idea, ideas, idea-row-body

#idea(
  "etal",
  title: [Et al.],
  tags: (note: none),
  created: datetime(year: 2026, month: 8, day: 20),
)[Attribution flattens a crowd into one name.]

#context html.elem("ul", ideas(tagged: "note").map(e => html.elem(
  // the `<li>` is the caller's, with its own classes and attributes
  "li",
  attrs: (class: "my-row", data-my-kind: "note"),
  idea-row-body(
    when: e.created.display("[day] [month repr:short]"),
    iso: e.created.display("[year]-[month]-[day]"),
    title: e.label,
    href: e.href,
  ),
)).join())

The split is forced rather than tidy: @rookery/search ships two widgets that want this shape and disagree about who owns the <li>. Its filter panel builds its own list and uses #idea-row as the item; its general panel wraps whatever it is handed in an item of its own, which with #idea-row would nest one <li> inside another.

[idea:ideate-reference]#ideate

The one place in rookery where an idea is inferred rather than written. #ideate takes a block of content and mints ideas from it, either as a plain function on one block or as a document show rule — #show: ideate at the top level hands it the rest of the document. It is opt-in either way, and on a paged target it is a passthrough: a PDF of a block of prose is that block of prose.

Argument	Type	Description
`body`	content	The content to mint ideas from. The sole positional argument, which is what lets the function double as a show rule.
`separator`	function \| none	What starts a new idea: `par` (or `parbreak`) for one idea per paragraph, `heading.where(level: n)` for one per section, or `none` — the default — to mint the whole body as a single idea. A heading standing alone is passed through as structure rather than wrapped as an idea of its own.
`title`	content \| function \| none	A title given to every idea minted, or a function `(content, labels) => content` called on each section’s separating heading to compute its own. The function form is heading mode only, and the heading leaves the body when it is used, since the title is already rendered as the idea’s heading.
`name`	function \| auto	A function `(content, labels) => str` computing each idea’s name from its separating heading — `slug` is exported for exactly this. Defaults to auto, which slugs the heading the same way an unnamed `#idea`’s title is slugged, falling back to `#idea`’s own untitled-naming rule when the heading yields no usable slug. A fixed value is refused, as it would mint every idea in the body under one name.
`tags`	str \| array \| dictionary \| function	Tags put on every idea minted, in the same forms `#idea` accepts, or a function `(content, labels) => tags` computing each section’s own. An `#ideate-tag(..)` beacon placed in a section’s content adds to these, and wins on a conflicting key.
`display`	dictionary	As on `#idea`, and read by every idea minted — see below.

Two of the nine keys invert #idea’s own defaults, and are given here as they are read when nothing is said:

#show: ideate.with(
  display: (
    // an inferred idea is not one anybody named, and a frame around
    // every paragraph is chrome nobody asked for
    frame: false,
    // with more force: an inferred idea's name is a sequence number,
    // which tells a reader nothing
    name: false,
  ),
)

The remaining seven keys — title, date, tags, context, backlinks, label and background — carry their #idea meanings and defaults. As there, each key is also an argument in its own right, with the prefix restored, and an argument on the same call wins over the dictionary’s value for that key.

Every other #idea argument is forwarded to every idea minted. Note that those names are generated rather than authored, so an idea that has to be linkable is written by hand.

[idea:ideate-tag-reference]reference

`#ideate-tag`

A beacon that tags the idea minted around it, written inside the prose rather than at the #ideate call site. It takes tags in the same four forms #idea’s own tags argument accepts — nothing, one name, a list of names, or a dictionary carrying metadata — and adds to whatever #ideate(tags: ..) already put on every idea, winning on a key the two disagree about.

#show: ideate.with(separator: heading.where(level: 2), tags: "note")

== A section
#ideate-tag(("draft", "phd"))
Its prose, minted as an idea tagged note, draft and phd.

Under separator: heading the beacon may sit anywhere in the section’s content; inside a paragraph it tags the group it is written in. It renders nothing of itself.

[idea:ideate-name-reference]reference

`#ideate-name`

The same device for a name: a beacon naming the one idea minted around it, overriding whatever name would otherwise have derived.

== A section
#ideate-name("the-name-i-want")
Its prose, minted under `idea:the-name-i-want`.

Unlike a name function, this works under every separator — it carries its own value rather than reading one off a heading — which makes it the way to pin the one inferred idea that has to be linkable without naming the rest.

[idea:slug-reference]reference

`#slug`

A URL-safe slug from content or a string: lowercased, every run of characters outside a–z and 0–9 collapsed to a single hyphen, with none left at either end.

#import "@rookery/core:0.1.0": ideate, slug
#show: ideate.with(
  separator: heading.where(level: 2),
  name: (h, labels) => "sec-" + slug(h),
)

Exported for exactly that: the name function above, naming each section’s idea after its own heading, so inserting or reordering sections does not renumber every name after it.

Text that is nothing but punctuation slugs to the empty string, and the build fails rather than minting an idea under an empty name.

[idea:window-reference]#window

A window shows an idea inside another page — its title, its permalink and its body, as one foldable block. It is pure presentation: a window registers nothing, mints no page and never re-registers the idea it transcludes, so one idea can be windowed anywhere and as often as it earns.

The ideas shown are named, or selected by tag, or both. Selection is rookery-wide, since the registry a window reads is the whole rookery’s — where the window sits makes no difference to what a tag pulls in.

Argument	Type	Description
`names`	str \| label \| array	The idea to show, or an array of them. A name is written bare (`"etal"`) or in full (`"idea:etal"`), as a string or a label, so `#window("etal")` and `#window(<etal>)` are the same call. Several are passed as one array — `#window(("a", "b"))` — and may be omitted entirely when `tags` does the selecting.
`tagged`	str \| array \| dictionary	The tags whose ideas to show, instead of naming them or alongside it. A window shows the union of the two, and an idea that is both named and tagged appears once, where it was named.
`match`	str	Whether a tagged idea has to carry `"any"` of the tags — the default — or `"all"` of them.
`filter`	function \| none	A predicate of your own over the idea’s tag dictionary, ANDed with `tagged` and `match` rather than replacing them. It is what expresses a selection those two cannot: an exclusion, or an OR of ANDs. The same argument `#ideas` and `#outline` take. On `#window`, the ideas it selects also register no backlinks, for the reason given below.
`sort`	str \| auto	The order the ideas are shown in. auto, the default, keeps the named ideas in the order they were written and appends the tag matches by name; `"date"` and `"lexicographic"` order the whole selection instead.
`unfurl`	int \| auto	How far transclusion nests. `0` renders the idea as a link to its own page and transcludes nothing, `1` renders it and collapses any window written inside it to a bare permalink, and `n` unfurls `n - 1` levels of those. Defaults to the rookery-wide `#rookery(window-unfurl: ..)`, itself `1`. Windows are all that count: an idea written inside a transcluded body is rebuilt in full whatever the budget.
`limit`	int \| none	How many blocks of the body to show — a block being a paragraph or a list, the unit that can be cut without leaving half a sentence. The whole body by default; in HTML and EPUB every footnote in the note is listed regardless, since the tail sits collapsed rather than dropped, and one written in the shown blocks renders twice — under a paged target, where the tail is truly dropped, only the footnotes that survive the cut are listed.
`folded`	bool	Whether the window starts closed, leaving its summary alone on the page until a reader opens it.
`foldable`	bool	Whether there is a disclosure at all. `false` renders the body with nothing to click and nothing that can hide it — for a window that is the thing being read rather than a reference to it, such as a slide, where a stray click folding it shut would be a bug. It makes `folded` inert.
`reserve-title`	bool	Whether a titleless window keeps the blank line its summary reserves for the title it does not have. Dead space above a slide’s body; no effect on a window whose idea has a title.
`backlink`	bool	Whether the window counts as a link from the page it sits on to the idea it shows. True is right for a window written into an idea’s prose; `false` is for a derived view — a deck, an index, a preview — which renders an idea rather than pointing at it, and should not fill that idea’s backlinks with pages nobody wrote a link on. `true`, the default, means every idea the window shows gains a backlink from it, named or tagged alike.
`display`	dictionary	What the window shows of itself, as a dictionary of six flags — see below.

As on #idea, every display key takes a boolean and defaults to auto, the rookery-wide setting given to #rookery(display: ..).

#window(
  "etal",
  display: (
    // a titleless idea is named by the label derived from its first
    // line; false names it only where it carries an authored title
    label: true,
    // the `created` date sits at the right-hand end of the summary
    date: true,
    // the tags are worn in the summary as pills, metadata tags excepted
    tags: true,
    // the window is drawn as a card, with its left rule and indent
    frame: true,
    // the name is shown in the summary as a permalink
    name: true,
    // the window takes a tint under the cursor
    background: true,
  ),
)

Each key is also an argument in its own right, with the prefix restored — display-frame: false — and an argument on the same call wins over the dictionary’s value for that key. #idea’s three remaining keys, title, context and backlinks, describe an idea’s own minted page rather than a window onto it, and a window reads none of them.

A tag selection backlinks exactly as a named one does: every idea a tagged window matches takes a backlink, both from the page the window sits on and from the idea whose prose it is written in. The one selection that registers nothing is filter—a predicate cannot ride in the metadata the backlink walk reads, and it is ANDed with tagged rather than replacing it.

[idea:outline-reference]#outline

A contents list over the ideas in your rookery, derived from how you nest them. See outlining ideas for what it lists and what it leaves out.

Typst’s own idiom for an outline over something other than headings is a target: argument, so rookery overloads that call rather than asking you to remember a second name:

#import "@rookery/core:0.1.0": idea, outline
#outline(target: idea, scope: "page", depth: 2)   // the ideas on this page
#outline()                                        // Typst's own, over headings

target: idea takes the arguments below; every other target proxies straight through to Typst’s #outline, unchanged. Passing tagged, match, filter or scope without target: idea is refused by name, rather than forwarded into Typst’s outline to be rejected there with a message about an argument you did not think you were writing.

Argument	Type	Description
`title`	content \| auto \| none	The label above the list. auto prints ‘Contents’, matching Typst’s own `#outline`; none omits it; any other content replaces it. Rendered as a real heading that neither self-lists in a later outline nor takes the document’s heading numbering.
`depth`	int \| none	How many levels of nesting to show, counted as Typst counts heading levels: a top-level idea is `1`. Levels of containment, not of pages.
`scope`	str	How wide to cast: `"rookery"`, the default, lists every idea in the rookery as one tree in spine order; `"page"` narrows to the ideas written on this page. The whole spine compiles as one document, so the wider reading costs nothing extra.
`tagged`	str \| array \| dictionary \| none	The tags to restrict the outline to.
`match`	str	Whether a listed idea has to carry `"any"` of those tags — the default — or `"all"` of them.
`filter`	function \| none	A predicate over the idea’s tag dictionary, ANDed with the two above. The same trio `#window` and `#ideas` take.

Filtering happens before depth is applied, and that order is the point: depth: 1 means the top level of what you asked for, not whatever survived from the top level of everything. An idea whose parent was filtered out is promoted to its nearest surviving ancestor’s level rather than left dangling.

Rows are not grouped under per-page headings. An idea’s name is flat and travels between files precisely so a reader never has to know which file holds it; an index that led with filenames would put that back.

The same function is exported as #ideas-outline as well, taking the same six arguments with no target: to write:

#import "@rookery/core:0.1.0": ideas-outline
#ideas-outline(scope: "page", depth: 2)

Prefer #outline. Reach for #ideas-outline where you would rather not shadow Typst’s own #outline at all — a project that imports this package with *, or one with show outline: rules of its own to keep clear of. Nothing is lost by the shadow itself, since every non-idea target proxies through untouched; what you are choosing is whether the name in your file is Typst’s or rookery’s.

[idea:ideas-reference]#ideas

Your rookery’s contents are always also available in Typst through the #ideas() function. This function returns all of your ideas as a data structure that you may then use to customize your rookery or power downstream applications. ideas has to be called inside #context, since it reads the rookery’s registry:

#import "@rookery/core:0.1.0": ideas
#context {
  for e in ideas(tagged: "concept") [- #link(e.href, e.label)]
}

Argument	Type	Description
`tagged`	str \| array \| dictionary \| none	The tags to narrow the corpus to. The same argument `#window` and `#outline` take, with the same meanings.
`match`	str	Whether a matching idea has to carry `"any"` of those tags — the default — or `"all"` of them.
`filter`	function \| none	A predicate over the idea’s tag dictionary, ANDed with `tagged` and `match`. Applied before the row is built, so an idea you drop never pays for its own conversions — which is the whole reason it is an argument here rather than a `.filter()` on the result.
`sort`	str \| auto	The order the rows come back in. auto and `"lexicographic"` both mean by name; `"date"` puts the newest `created` first and undated ideas last.
`index`	dictionary \| none	A `#tag-index` projection, whose declared fields are merged onto every row. The supported way to filter or sort on a tag value.
`values`	bool	Whether each row also carries a `tags-dict` field holding the idea’s whole tag dictionary, values included. Off by default, and absent rather than empty when off, so a consumer cannot read `(:)` off a row and conclude the idea is untagged.

Each row is a dictionary of ten fields, in every call:

Field	Type	What it holds
`id`	str	The full name, prefix included — `"idea:etal"`.
`name`	str	The same name with the prefix stripped — `"etal"`. What every accessor on this page takes.
`title`	content \| none	The authored title, as content, refs and all. none where the idea has none.
`text`	str	That same title as plain text, `""` where there is none. A reference inside it reads as its target’s name rather than as a number.
`label`	str	What to call this idea, and never empty: the title as text, else the body’s first sixty characters, else the idea’s own name. Reach for this wherever an idea is referred to rather than rendered — a row in an index, a node in a graph, a sort key — and the `if r.text == "" { r.name }` dance stops being yours to write.
`tags`	array	The tag names, every key including the valued ones, `()` where there are none. A flat array of strings, so it drops into a JSON index unchanged. Tags are unordered and nothing may depend on the sequence; the values live in `tags-dict` and `#tag-data`.
`body`	str	The idea’s body as plain text, `""` where it is empty — matchable and excerptable, but not renderable. `#idea-body` is how you render one.
`href`	str \| none	Where the idea’s minted page sits from the page this was called on. See `#idea-href`.
`page`	str \| none	The same page from the site root. See `#idea-path`.
`created`	datetime \| none	The idea’s date.

Three things are deliberately not here in bulk: the body as content, the backlink graph, and the tag values. The first would make every consumer a second transclusion engine; the second is the minted page’s own business; the third can be a datetime or content, which a JSON index encodes as a silent blob. This list is a contract other packages are written against, so a field is added rather than changed.

[idea:tag-index-reference]reference

`#tag-index`

A declared projection of tag values onto an #ideas row. It exists because a tag’s value is arbitrary and a row’s fields must be encodable; a projection makes the value narrow and checked, which is what lets it ride a row at all.

#import "@rookery/core:0.1.0": ideas, tag-index

#let INDEX = tag-index((
  cycle: (family: "cycle-"),                      // -> "26-27"
  kind: (family: "venue-", one-of: KINDS),        // -> "postdoc"
  deadline: (key: "date-deadline", stamp: true),  // -> "20261101"
  stage: (from: stage-of),                        // derived
))

#context {
  for e in ideas(index: INDEX) [- #e.kind, due #e.deadline]
}

Each field names exactly one extractor:

Form	What it projects
`key: "<tag>"`	That tag’s value, or none where the idea does not carry it.
`family: "<prefix>"`	The first flat tag whose key starts with the prefix, prefix stripped. `one-of:` restricts and orders the candidates, so an idea carrying two of a family resolves to the earliest you listed rather than to whichever key order happens to yield first.
`from: <function>`	Called with the idea’s whole tag dictionary. A derived value — the current stage of a dated log, how far something got — is a computation rather than a tag value, and this is the only form that makes one filterable or sortable.

Any of the three may carry stamp: true, which renders a datetime as a zero-padded [year][month][day] string. That is not only a display choice: a fixed-width numeric string sorts lexically in date order, so a stamped field is a free sort key.

A projected value must be a scalar — a string, an integer, a float, a boolean or none — and the build fails where one is not. A field may not take the name of a row field above, for the same reason: naming one href and silently replacing every link on the page is the failure this refusal prevents.

[idea:tag-data-reference]reference

`#tag-data`

Every registered idea’s tag dictionary, keyed by full name. The bulk accessor a package builds on when it needs tag values across the whole rookery, where #idea-tag-names and #idea-tag-value answer for one idea at a time.

#import "@rookery/core:0.1.0": ideas, tag-data
#context {
  let tags = tag-data()
  // -> ("idea:etal": (phd: none, priority: 1), ..)
  for e in ideas() [- #e.label: #repr(tags.at(e.id))]
}

Takes no arguments, and must be called inside #context. One #ideas plus one #tag-data covers the corpus, and the two join on id — which is the point, since the per-idea accessors each resolve the registry again and walking a rookery through them pays that cost once per idea.

Values are arbitrary Typst values: datetimes, arrays, content, whatever a package put there. Do not serialize this wholesale into a page.

It is not called tags(), though that is the obvious parallel with #ideas: tags is a parameter name on #idea, #ideate and most of this package’s constructors, so a bare tags() would be shadowed by that parameter inside every one of their bodies.