You can reference an existing idea by creating either a hyperlink or a window. Both kinds of references use the idea’s name, which is unique in a global namespace.
Names are normal Typst labels, meaning that compilation will fail if there is a duplicate. To ensure that rookery’s labels don’t easily clash with ones you create yourself, the prefix idea: is prepended to all of your idea names. You can customize this prefix when you configure rookery.
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.
When you compile a rookery with Rheo, each idea that you declare will produce its own standalone page. When you link to an idea using a hyperlink, by default it will link to that idea’s standalone page. (To link to the page in which the idea was actually declared, see #hyperlink.)
The standalone page will be minted at ideas/<idea-name>.html, where <idea-name> is the name you give explicitly or the one that is implicitly generated. The ideas directory is configurable through the prefix setting (see the site-config reference).
#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.
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.
An idea that windows onto itself, or two ideas that window onto each other, can constitute an infinite loop that could therefore unfurl forever. In order to prevent this, rookery has a notion of window unfurl, which is set to 1 by default.
When a window is called at a level of recursion greater than the unfurl budget, rookery renders a call to #window as a link to the idea’s standalone page rather than as transcluded content. It’s best to think of window unfurl as a multiplier, as the amount of work rookery needs to do multiplies when you raise it.
You can set the unfurl budget per window, or site-wide:
#show: rookery.with(window-unfurl: 1)
#window(<first-idea>)
#window(<first-idea>, unfurl: 2)Here is a window on this selfsame idea. Because this documentation uses the default unfurl of 1, it only recurses as a window once, and then bottoms out as a link:
An idea that windows onto itself, or two ideas that window onto each other, can constitute an infinite loop that could therefore unfurl forever. In order to prevent this, rookery has a notion of window unfurl, which is set to 1 by default.
When a window is called at a level of recursion greater than the unfurl budget, rookery renders a call to #window as a link to the idea’s standalone page rather than as transcluded content. It’s best to think of window unfurl as a multiplier, as the amount of work rookery needs to do multiplies when you raise it.
You can set the unfurl budget per window, or site-wide:
#show: rookery.with(window-unfurl: 1)
#window(<first-idea>)
#window(<first-idea>, unfurl: 2)Here is a window on this selfsame idea. Because this documentation uses the default unfurl of 1, it only recurses as a window once, and then bottoms out as a link:
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.
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:
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.