[idea:rookery-bibtex]alpha-package2026-08-20

`@rookery/bibtex`

Reads a .bib file and mints one idea per reference, keyed and titled from the entry itself, so a work is a note like any other and anything that cites it says so with a backlink.

Write a citation by hand where you have something to say about the work, and sweep the rest of the bibliography with all().

#import "@rookery/core:0.1.0": rookery
#import "@rookery/bibtex:0.1.0": bibtex
#show: rookery

/* Typst cannot call a dictionary key directly, so bind the factory's
   functions once rather than writing #(refs.citation)(..) at every call. */
#let refs = bibtex(read("references.bib"))
#let citation = refs.citation
#let citations-as-ideas = refs.all

/* The BibTeX key names the note, written as a ref, a bare label or a string.
   The title comes off the entry as "Badiou, Ethics (2002)", and the note is
   tagged `citation` alongside whatever tags: you add. */
#citation(<badiou2002>, tags: "essay")[
  Read against Handelman, since it treats the same refusal of mathematics as
  a question of ethics rather than of method.

  /* The entry's own fields, as a definition list. */
  #refs.fields("badiou2002")
]

/* Every entry no hand-written citation has claimed, in key order. Call this
   once, from one vertebra — a register page the bar never lists, which the
   pages a reader browses transclude by tag. */
#citations-as-ideas()

Reading a reference manager’s export

Zotero writes rows that belong to the library rather than to the work, and a library holds far more than a project cites. Narrow and trim at the factory, once.

#let refs = bibtex(
  read("references.bib"),
  /* Parse these keys alone, so a fourteen-hundred-entry export costs what
     the project actually cites and mints as many notes. */
  only: ("badiou2002", "handelman2019"),
  /* Turn Zotero's own keywords into rookery tags, then hide the raw row
     they came from. */
  keywords: "all",
  show-fields: ("keywords": false, "urldate": false, "file": false),
)

Bibtex

[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:alpha-packages]The following packages are alpha software, and thus subject ...

The following packages are alpha software, and thus subject to API breakages, bugs, and unlikely behavior. Use them at your own risk!

In order to take this risk, you need to update your Rheo project to use rookery’s dev branch:

[packages.rookery]
repo = "https://github.com/freecomputinglab/rookery"
branch = "dev"

@rookery/bibtex

@rookery/cfps

@rookery/meetings

@rookery/pinboard

@rookery/search

@rookery/slipshow

@rookery/timeline

@rookery/todos

Index