Rookery - Hyperlinks

[idea:standalone-idea-pages]Standalone pages for ideas

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

[idea:config-reference]Argument reference

Parameter	Default	What it sets
`prefix`	`"idea"`	The namespace an idea’s name lives in; non-empty, no `:` (the separator is added for you). See referencing ideas.
`note-dir`	`none`	The directory the minted idea pages are written to. Left unset, it is `ideas` under the default prefix, and the prefix itself under any other — `prefix: "maths"` mints `maths/`, not `mathss/`. Names one directory: no `/` and no `:`.
`css-prefix`	`none`	The stem every class this package emits is built from. Left unset, it follows `prefix`, so renaming the name namespace renames `.idea-box` to `.note-box` along with it; set it to hold the classes still while the names move. See HTML class reference.
`window-unfurl`	`1`	How many levels of transclusion are allowed before a window bottoms out as a link to the idea’s own page. `0` allows none. See controlling window unfurl.
`theme`	`(:)`	The ten keys the package will style for you — five colors, three lengths, a font stack, and `tags-color`. Every key but `tags-color` is also a parameter in its own right, and the granular form wins. See theming a rookery.
`display`	`(:)`	What every idea and window in the rookery shows of itself, as a dictionary of the same nine flags `#idea` takes. This is the bottom of the stack: an idea or a window that leaves a key at auto is asking for the value set here. `date` and `tags` resolve to `false` when nothing is said, the other seven to `true`. Each key is also a parameter in its own right — `display-date: true` — and the granular form wins. See `#idea`.
`idea-page-template`	`none`	Your own chrome for the standalone page rookery mints per idea. See idea template.
`bibliography`	`none`	Typst’s own `#bibliography` arguments, for the single bibliography a rookery’s citations all draw from.
`index-page`	`true`	Whether to mint `ideas/index.html`, a landing page listing every idea in the rookery. It goes in the same directory the idea pages do, so a rookery that moved them with `note-dir` or `prefix` gets `maths/index.html` rather than `ideas/index.html`. Set it to `false` where your site already publishes an index of its own.
`refs`	`true`	Whether rookery installs the `show ref:` rule that renders `@idea:etal` as the idea rather than a figure number. Set it to `false` to keep Typst’s own behavior, or to install a rule of your own. See hyperlinks.
`hyperlink-target-minted`	`true`	Where every `@idea:etal` in the document lands: `true` on the idea’s standalone minted page, `false` in the context it was hatched in. The same parameter `#hyperlink` itself takes. Ignored when `refs` is `false`. See hyperlinks.
`syndicate`	`false`	Whether each minted page also carries a `<feeds:item>` beacon — the label `@rheo/feeds`’s `items()` reads by default — so a feed package can collect your ideas without either package importing the other. Off by default: a package should not write into another’s label namespace unasked. An idea with no date never gets one.
`page-titles`	`"title"`	What the context and backlinks footer on an idea’s page calls the pages it lists: `"title"` is Rheo’s own spine title, `"path"` the source path with the content directory and the extension dropped — `jobs/cfps`, `institutions`. Rheo derives a title from the file stem, so in a project with a page per directory every `index.typ` is titled ‘Index’, which is a poor answer to a footer asking where an idea was written; a path is longer and plainer, and unique by construction. A rookery-wide choice, since one idea’s footer disagreeing with another’s about what a page is called would be worse than either answer.
`invisible-tags`	`()`	Tags that leave no trace in the HTML: no pill in any hat, no `.idea-tag-<tag>` class on the heading, the card, an outline row or an index row, and no generated rule for a `tags-color` entry naming one. Filtering still sees them everywhere — `#window(tagged: ..)`, `#ideas`, `#idea-tag-names`, a search query — which is what makes an invisible tag usable as a build-level key. The presentational complement to `exclude-tags`, which drops the idea itself.

[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:hyperlink-reference]#hyperlink

A plain link to an idea, and the renderer behind every @idea:etal in your prose. For how a hyperlink reads alongside a window, see hyperlinks.

#import "@rookery/core:0.1.0": hyperlink
#hyperlink("etal")[see this]
#hyperlink(<etal>, hyperlink-target-minted: false)[see this, in context]

Argument	Type	Description
`name`	str \| label	The idea to link to, written bare (`"etal"`) or in full, as a string or a label. Positional, and required in a direct call.
`body`	content	The link text. Positional, and required: an explicit call has no title to fall back on, where `@idea:etal` does.
`hyperlink-target-minted`	bool	Where the link lands: `true`, the default, on the idea’s own minted page, `false` on the anchor where it was hatched.

The same function is @idea:etal’s renderer, installed as a show ref: rule. An idea’s label lives on a hidden anchor, so without the rule a bare reference resolves to that anchor and renders as a figure number — #show: rookery installs it for you, and refs: false declines it.

#show ref: hyperlink                                         // the minted page
#show ref: hyperlink.with(hyperlink-target-minted: false)    // the anchor

In reference mode the link names its target: the idea’s title, or the name derived from its first line where it has none, or its bare name as a last resort — the same name an index row and a search hit call it by, so the three cannot disagree. @idea:etal[custom text] overrides that.

Existence is checked at the call site, so a typo fails the build rather than shipping a dangling link. An idea excluded from the build is a different matter: the body stays and only the link goes, since a hyperlink sits inside a sentence you wrote and deleting it would break the grammar around it.

Index