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.

You can add tags to any idea. Tags work as a lateral filter across many ideas that you can use to group windows on them, group outlines, or filter ideas in a search modal.

#idea(
  "meeting-notes",
  tags: ("draft", "review"),
)[ ... ]

/* Window over all ideas with the tag "draft" */
#window(tagged: "draft")

Beneath their appearance as simple strings that can be used to organize ideas, tags are implemented as hash maps using strings as keys and abstract types as values. This means that you can use them to build up complex data structures that function as metadata for more structured ideas:

#idea(
  title: [An idea with complex metadata],
  tags: (
    "opened": datetime(year: 2026, month: 9, day: 19),
    "expected-length": duration(days: 2, hours: 1, minutes: 30),
    "details": ("a": 1, "b": 2),
  ),
)

For an example of treating tags as metadata to create more structured idea variants, see @rookery/timeline.

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.

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

Hyperlinks are the lowest-touch way to reference an idea in rookery, and are implemented as regular Typst references. Say you have an idea:

#idea("first-idea", title: [My first idea])

The following three bullets all produce the same result: a hyperlink that reads ‘My first idea’ to the idea’s standalone page.

#import "@rookery/core:0.1.0": hyperlink
- @idea:first-idea
- @idea:first-idea[My first idea]
- #hyperlink(<first-idea>)[My first idea]

Note that you must use the idea: prefix (which you may customize) when you are using references in the Typst namespace. When using the #hyperlink function imported from rookery, you may omit the prefix if you choose.

Creating a hyperlink to an idea will add it to that idea’s set of backlinks.

• Reference documentation for #hyperlink.

Windows can be used to interpolate the entirety of an idea’s content into a different context. They are useful in home pages or other sections that aggregate content.

Fundamentally, windows are a form of augmented hyperlink. They take their name from Ted Nelson’s notion of the transpointing window as they allow you to see the content on either side of the link (like a window).

Say you have an idea:

#idea("first-idea", title: [My first idea])

You can produce a window on this idea like so:

#import "@rookery/core:0.1.0": window
#window(<first-idea>)

Note that we do not need the idea: prefix. Like #hyperlink, #window is a function imported from rookery that already knows which namespace to look in.

By default, this window will be unfolded, showing the full content of the idea.

• Reference documentation for #window.

#show: rookery.with(window-unfurl: 1)
#window(<first-idea>)
#window(<first-idea>, unfurl: 2)

You can outline the ideas in a context like so:

#import "@rookery/core:0.1.0": idea, outline
#outline(target: idea)

Typst’s own way of outlining something other than headings is to name it with target:, so rookery overloads that call rather than asking you to learn a second one. target: idea outlines your ideas; every other target—the default heading, a figure kind, anything else—passes straight through to Typst’s #outline unchanged.

This outline is derived from how you nest #idea hatchings, and lists every idea in the rookery by default—pass scope: "page" to narrow it to only the ideas written on this page. As windows are only echoes of ideas that live elsewhere, they are not included.

• Reference documentation for #outline.

The ordering of ideas across site-wide outlines will hew to the Rheo spine’s order (which is lexicographic by filename by default), with index.typ first.

When you declare an idea without a name, rookery will generate one for you. Because a compiled rookery is a pure function of the files that are on disk, however, auto-names may drift as you move and edit the idea.

Rookery will make a best effort to give your idea a unique name through the following heuristic:

1. Use a kebab-case version of the idea’s title.
2. For ideas without a title, construct a name from recombining and hashing the body content.

This heuristic is not guaranteed to produce unique names for all ideas. When you have two ideas without a title and the same body content, for example, the auto-name for both ideas will be identical. When two or more ideas have the same name, your rookery’s compilation will fail.

Due to the lack of a uniqueness guarantee and the instability of auto-naming, we recommend explicitly naming all ideas in your rookery. If you don’t care about choosing your ideas’ names, you can consider simply copying the auto-name from the browser and pasting it into Typst. Auto-naming exists so that inventing a name for each idea does not gate its inclusion in the rookery, but it should be treated as a provisional band-aid rather than a load-bearing mechanism.