Tutorial: your first manuscript in 15 minutes
This tutorial walks one path. By the end you will have a Quarto manuscript with citations resolved automatically from DOIs and PubMed IDs, rendering itself on every push, deployed to GitHub Pages with a /v/<commit-sha>/ immutable permalink for each commit.
Budget: 15 minutes if you have Quarto, uv, and gh already on your machine. First render takes longer because Quarto installs TinyTeX the first time it sees a PDF format. After that, every render is fast.
You will not learn why the design choices are this way — that’s the Design and Citation pipeline pages’ job. This tutorial is doing, not understanding.
This page is itself rendered through the quartobot pre-render hook plus Quarto. The citation you see in the next paragraph — (Wickham et al. 2019) — was resolved by quartobot resolve at render time, the same way it would be in your manuscript. Every example output block on the page was captured from a real quartobot invocation while this page was being built.
To set the example: the tooling that makes a Quarto manuscript self-rendering, citation-resolving, and version-banner-aware draws on the broader Quarto + pandoc-citeproc ecosystem; for the data side of a typical manuscript, the tidyverse (Wickham et al. 2019) is the most-cited starting point in R, single-cell methods like Seurat (Stuart et al. 2018) anchor a lot of methods-paper bibliographies, and transformer architectures (Vaswani et al. 2023) for LLM-driven analysis tooling, and reference datasets (“The Genotype-Tissue Expression (GTEx) Project.” 2013) anchor the biological claims a paper makes. Those four citations live in this paragraph, were resolved by quartobot resolve against their registrars (Crossref, bioRxiv via Crossref, PubMed), and pandoc-citeproc formatted the inline citations and bibliography section below.
Before you start
You need:
- Quarto ≥ 1.4 —
quarto --version. Install Quarto if needed. uv—uv --version. Install uv if needed; it handles the Python install for you transparently.gh(the GitHub CLI) —gh --version. Install gh if needed.- A GitHub account authenticated with
gh auth login.
That’s it. No separate Python install, no quarto add step, no Quarto extension to install — uv tool install quartobot brings everything along, including the resolver library.
1. Install quartobot
uv tool install quartobotThis puts quartobot on your user PATH so Quarto’s pre-render subprocess can find it without venv activation. Confirm:
#| echo: true
quartobot --versionYou should see quartobot, version 0.2.0 or later.
2. Create the project
Use Quarto’s own scaffolder for the project shape:
quarto create project manuscript my-paper
cd my-paperQuarto writes a manuscript-shaped directory: an index.qmd, a _quarto.yml, and the layout pandoc expects for a single-document manuscript.
3. Wire in citation resolution
Layer the citation pipeline on top:
quartobot initinit adds two new files and modifies .gitignore: a seed references.bib you can hand-curate any non-registrar references into, plus .gitignore lines for _book/, _freeze/, .quarto/, *_files/, **/*.quarto_ipynb, and references.json. Because quarto create project already wrote a _quarto.yml, init won’t touch it; instead it prints a YAML snippet to paste in yourself. Copy the snippet and merge it into your _quarto.yml under the existing project: block — it adds the pre-render: line plus a bibliography: list with both references.bib and references.json.
That’s the minimum. If all you want is citations resolved from @doi: and friends, stop here.
4. Write a paragraph with real citations
Open index.qmd and replace the body with a paragraph that uses the cite keys quartobot supports. Authors who write the prose below get the rendered references below it for free — no hand-curating a .bib per source.
The tooling stack for a modern computational manuscript spans
several sources. The tidyverse [@doi:10.21105/joss.01686] gives R
users a coherent grammar for data manipulation. Single-cell
integration approaches like Seurat [@doi:10.1101/460147], still on
bioRxiv as a preprint, sit alongside transformer architectures
[@arxiv:1706.03762] for the LLM-driven tooling now common in
analysis pipelines. Reference datasets like the Genotype-Tissue
Expression Consortium's pilot analysis [@pmid:23715323] anchor the
biological claims.Four cite keys, four registrars (Crossref, bioRxiv via Crossref, arXiv, PubMed). Save the file.
5. See what quartobot scan reports
Before rendering, ask quartobot what citations it sees. The same prose you just wrote, scanned by quartobot scan:
#| echo: true
quartobot scan fixtures/sample-paper/That’s the inventory the pre-render hook will resolve when quarto render runs. Each prefix groups its keys; the summary line reports the total.
6. Render locally
quarto renderFirst render installs TinyTeX (Quarto handles this; takes 1–2 minutes). On the second render and after, it’s seconds.
The pre-render hook fires before pandoc runs. It:
- Scans
index.qmdfor cite keys. - Calls each registrar (Crossref for the DOI, PubMed for the PMID, arXiv for the arXiv preprint) to resolve canonical metadata.
- Writes the resulting CSL JSON to
references.json. - Hands control back to pandoc, which reads
references.jsonand formats the citations.
Open _output/index.html (or index.pdf). The citations show as formatted references with author names, journal, year. No empty [?] placeholders.
Re-run quarto render. Now it’s near-instant — the pre-render hook sees references.json already exists with all keys cached, skips the network round-trip, and pandoc renders straight through.
7. Add the publish-on-every-commit CI
If you want every push to your GitHub repo to render the manuscript, deploy it to GitHub Pages, embed a “this version: <sha>” banner in the rendered HTML, and post a sticky preview comment on each PR — add the second layer:
quartobot use github-ciThis scaffolds .github/workflows/render.yml (the trigger), the PR-preview cleanup workflow, the version-banner Quarto include, and prints a YAML snippet to merge into your _quarto.yml so the banner appears in the rendered HTML.
Skip this step entirely if you already have CI you’re happy with, or if you plan to publish via quarto publish. The citation pipeline from step 3 works the same either way.
For the full set of inputs you can override on the scaffolded workflow (formats, manuscript-name, quarto-version, project-title, etc.), see Workflows and actions in the Reference section. Same page covers the composite actions if you’d rather compose your own workflow instead.
Add the snippet that quartobot use github-ci printed to your _quarto.yml. It will look roughly like:
format:
html:
include-before-body:
- _version-banner.html8. Push to GitHub
gh repo create my-paper --source=. --public --pushgh creates the repo, pushes your commit, and gives you the URL.
The render workflow fires on push. Watch it land:
gh run watchWhen the workflow finishes, GitHub Pages serves your manuscript at https://<your-handle>.github.io/my-paper/. Every commit also deploys to a versioned subdirectory: https://<your-handle>.github.io/my-paper/v/<sha>/index.html. The version banner in the rendered HTML links you between them.
9. Open a pull request
Make a change. Push to a branch. Open a PR.
git checkout -b add-context
# edit index.qmd, add another sentence with another citation
git add index.qmd
git commit -m "Add context paragraph"
git push -u origin add-context
gh pr create --fillWithin a couple of minutes a sticky comment lands on the PR with a link to a preview render. Reviewers see exactly what your branch renders to without checking it out locally.
When you merge the PR, quartobot use github-ci’s cleanup workflow removes the preview directory from gh-pages; the merge commit gets its own /v/<sha>/ permalink alongside the latest.
You now have
- A manuscript that builds itself on every push.
- Citations resolved from registrars at render time, cached so CI never sees a network blip mid-render.
- An immutable
/v/<sha>/URL for every commit anyone can cite. - PR previews via sticky comment.
- A version banner in the rendered HTML pointing at “this version” and “the latest version” of the paper.
Where to next
- CLI reference — every command, every flag.
- MCP server — point Claude Desktop, Codex, or Gemini Code Assist at
quartobot mcpso an agent can call theresolve_citationtool while you draft. - Migrating from manubot — if you have a manubot manuscript and want to translate the layout.
- Design — the architecture decisions and prior art.