quartobot

Citation resolution and manuscript-as-software CI for Quarto.
Paste a DOI in your prose. Render the manuscript. The bibliography is already correct.

---

uv tool install quartobot

Documentation: seandavi.github.io/quartobot · Source: seandavi/quartobot · PyPI: quartobot

What it does

Authors write persistent-identifier cite keys directly in prose:

We follow @doi:10.1371/journal.pcbi.1007128, with the dataset described
in @pmid:31479462 and methods inspired by @arxiv:2104.10729.

A Quarto project.pre-render: hook resolves each key to canonical metadata before pandoc-citeproc runs, writes the result to a references.json you can commit, and the manuscript renders the same way on every machine. No quartobot install needed at render time, no live Crossref / PubMed / arXiv hit per render. CI gets the same behavior the author saw locally, and a network blip mid-render is no longer a build failure.

Supported prefixes: @doi:, @pmid:, @arxiv:, @isbn:, @url:, @wikidata:, @pmc:, plus hand-curated keys from a project .bib. Resolution goes through manubot's citekey_to_csl_item — eight years of accumulated source-API quirks behind a single function call. quartobot itself doesn't reimplement resolution; it provides the Quarto integration, the CI scaffolding, and an agent-facing MCP surface.

Quick start

uv tool install quartobot
quarto create project manuscript my-paper
cd my-paper && quartobot init
# Optional: scaffold render + PR-preview CI.
quartobot use github-ci

That's the canonical path. Three other on-ramps live in Choose a path in for "I have an existing Quarto project" and the resolver-only minimum.

The CLI

Command	What it does
resolve	The pre-render hook. Invoked by Quarto from _quarto.yml's project.pre-render: line. Reads cite keys, writes CSL JSON.
scan / validate	CI-lint surfaces. Cite-key inventory and static _quarto.yml checks.
init	Scaffolds the citation pipeline into an existing Quarto project. Three files only.
use github-ci	Layers the render + PR-preview CI on top. Lean default; --with-versioned-snapshots for the manubot per-commit-permalink pattern.
reconcile	Resolves references.bib ↔ references.json citation-key collisions with explicit modes. Backup-then-mutate.
versions	Generates the /versions/ page on gh-pages — tagged releases + open PR previews.
mcp	Stdio MCP server. Agents in Claude Desktop, Codex, Gemini Code Assist call the same resolver as part of drafting.

Full reference: CLI and Workflows and actions.

Why this exists

manubot/manubot#332 ("Quarto integration") was opened by Anthony Gitter in April 2022 after a conversation with Sean Davis. Four years on, no PR, no assignee — but Quarto Manuscripts shipped as a first-party project type, and the integration turned out to be small once the resolver question was settled. This repo is the work to close that issue.

The longer story: Differences from manubot, Design, Citation pipeline.

Working example

seandavi/2026-venice-spatial-hackathon-manuscript runs the CI / permalink / banner half of the pattern on a live 25-author preprint from the Bioconductor Spatial Hackathon. That's the production reference the template lifted from.

See also

• Docs site: seandavi.github.io/quartobot — install, CLI reference, tutorials, migration guides, MCP setup
• Coming from another tool: Quarto · manubot · Zotero · LaTeX
• Release process: RELEASE_CHECKLIST.md — grounded in actual failure modes
• Contributing: CONTRIBUTING.md and CODE_OF_CONDUCT.md
• Changelog: CHANGELOG.md

Demo recording

The GIF above walks quartobot scan → quartobot resolve (live registrar lookups) → quarto render --to html → the formatted citation in the rendered manuscript. Recorded with asciinema (cast) + agg (cast → GIF). To re-record after changing the demo flow:

brew install asciinema agg
bash scripts/demo-setup.sh
asciinema rec docs/demo.cast --command 'bash scripts/demo.sh' --overwrite
agg docs/demo.cast docs/demo.gif --font-size 18 --theme dracula --speed 1.2 --cols 80 --rows 28
cp docs/demo.gif site/public/demo.gif  # also serves the landing-page embed

The scripts/demo.tape file is a vhs alternative for a higher-fidelity render once a Chrome/Chromium environment is available.

License

MIT.

---

Maintained by Sean Davis.
quartobot is an independent community project. It builds on Quarto but is not affiliated with or endorsed by Posit, PBC.