API surface

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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:

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.

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.