Citations

Press Cmd+Alt+C (or choose Document → Insert Citation…) and a picker searches two places at once: the .bib files in your project, and Zotero if it is running. Each row carries a Project or Zotero badge, and the footer says what was searched and what Zotero answered. Choose an entry and Suzuri inserts the citation at the cursor in whatever syntax the file wants.

With the cursor on a cite key, Cmd+Alt+O opens the PDF behind it in a split, in Suzuri's own PDF viewer.

Syntax per file type

The format follows the file extension, the same way typeset preview picks its compiler:

Multi-select in the picker inserts several keys in one citation.

The project owns its bibliography

{
  "citations": {
    "library": "refs/refs.bib"
  }
}

Every citation you insert is recorded in that one BibLaTeX file, relative to the project root. Pandoc, LaTeX, Typst, and Suzuri's own index all read it directly — there is no export step and nothing to keep in sync.

This is deliberately not how most Zotero integrations work. They keep an exported .bib mirroring your whole library and let an add-on choose keys, which is where the familiar complaints come from: stale exports, and keys that drift under citations you already wrote. Here an entry is pulled from Zotero once, at insert time, under a key Suzuri chose and will never change.

Zotero

Zotero must be running with its local API turned on. Zotero covers setup, how keys are chosen, where PDFs go, and what the picker's footer means when Zotero can't be reached.

When you insert a Zotero item, Suzuri fetches its BibLaTeX entry, appends it to your library, and, if Zotero has one, copies the attached PDF next to the library as <key>.pdf. That is the file Cmd+Alt+O opens later.

Completion and diagnostics

Every .bib file in the project is indexed. Typing @ in a citation context completes cite keys, and keys that resolve to no entry are styled as unresolved — but only once the index holds at least one entry, so a project that never cites anything sees no red ink.

Formatted references

In Markdown, a citation you can read is what shows: a group whose keys all resolve renders as the in-text form of the note's citation style, (Vaswani et al., 2017, p. 3) in APA or [1, p. 3] in IEEE, drawn as a chip. Put the cursor on it and the source [@key] comes back for editing. A heading named References, Bibliography or Works Cited renders the reference list for every work the note cites, in the style's order. Hovering a chip shows the full reference and its in-text form.

Suzuri renders with hayagriva, the CSL engine Typst uses, so a style renders the same way here as in Typst, Zotero, pandoc or Word. In .tex and .typ files the compiler does the rendering, so their style is whatever the document declares.

Pandoc syntax that renders

Locators pandoc knows are understood: p., pp., chap., sec., fig., vol., no., para., n., l., table, pt.. A group the renderer has no slot for, such as a prefix in [see @key], or one with a key that does not resolve, keeps its plain key chips.

Choosing a style

A document picks its style in the frontmatter; a document that names none gets APA:

---
title: A Paper
csl: ieee
---

The value is either the name of a bundled style or the path of a .csl file.

Bundled styles

About eighty styles from the official CSL repository ship inside Suzuri, compiled in, under a hundred-odd names. The ones most people reach for:

Short names such as apa are aliases; the long form (american-psychological-association) works too. The full list is Typst's built-in style list, which is the same archive.

A name that is not bundled does not break the note: rendering falls back to APA, and a warning line under the References heading names the value that failed and links back to this section. That is how a typo like csl: apaa shows up.

Your own .csl file

For a journal that is not bundled, point csl: at a file:

---
csl: styles/journal-of-marketing.csl
---

A relative path is looked up next to the note first, then from the project root. Suzuri reads the file through the project, so a change to it takes effect on the next render. A file that is missing or does not parse falls back to APA with a warning under References, except when its name matches a bundled style (styles/ieee.csl with no such file renders as ieee), which keeps pandoc-style frontmatter working as is.

Where to get the file:

• The Zotero Style Repository holds about 10,000 styles, one for nearly every journal. Search by journal name and download the .csl.
• The same files live in the citation-style-language/styles repository on GitHub.
• For a style nobody has written, copy the closest one and edit it, or use the visual CSL editor Zotero links to.

Most journal styles in the repository are dependent: a small file that only points at a parent style (Journal of Marketing points at the American Marketing Association style). Suzuri follows the pointer. When the parent is bundled, that is all you need; otherwise download the parent's .csl as well and put it beside the journal's file. The warning under References names the file and links straight to its download.