13  White Papers and References

Keywords

Quarto, reproducible publishing, coding agents, Markdown, Python, EPUB, data analysis, k-means clustering

A white paper is the one output that leaves the building and has to stand on its own. A client’s analyst, an investor’s technical adviser or a sceptical researcher will read it without you in the room, and will check it: whether the method is stated, whether the numbers in the text match the tables, whether the references exist and say what the paper claims they say. For a start-up, a benchmark or evaluation white paper is often the most credible thing it can publish, and the most damaging if one of those checks fails.

This chapter writes the evaluation’s white paper: numbered sections, an equation, a table and figures that the text refers to by number, citations in a standard style that read the same in the PDF, the Word file and the web page, references that a script confirms exist, and a house template for the PDF. The London and water projects each ended with an optional white paper (Section 9.6, Section 23.7); this is the full treatment, on the core path.

In this chapter
  • Name the parts of a technical white paper and the Quarto feature behind each: numbered sections, cross-references, citations, a citation style and a template.
  • Ask for a paper whose every figure, table and equation is referred to by number, and check that each reference resolves in every format.
  • Cite only what you have opened, in one citation style across HTML, Word and PDF, and check every DOI with a script.
  • Give the PDF a house template, and know when to use a journal’s instead.

Start fromyour acme-eval repository at the end of Chapter 12, or checkpoints/17-eval-site/.

You buildwhitepaper.qmd in PDF, Word and HTML, with references.bib, a citation style, a reference checker and a house template.

Checkpointcheckpoints/18-eval-whitepaper/

13.1 What a white paper is made of

Table 13.1: The parts of a white paper, and what each is called (Quarto 1.10.20).
Part Quarto calls it You check
sections a reader can cite number-sections: true, and ## Data {#sec-data} “Section 2” in the text, in every format
an equation, referred to $$ … $$ {#eq-auc} and @eq-auc “Equation 1”, a real equation in Word
a table or figure, referred to a cell labelled tbl-… or fig-…, and @tbl-… “Table 1”, “Figure 1”; no “??” anywhere
citations [@key] in the text, entries in references.bib each one appears in the reference list
a citation style csl: naming a style file, such as APA’s the same style in every format
the same style in the PDF citeproc: true under typst: no second “Bibliography” heading
a reference manager a .bib exported from it, such as Zotero’s the export’s entries match the sources
a house look a Typst template partial; a Word reference document the title block and footer, in the brand
a journal’s look quarto use template quarto-journals/<name> the journal’s own instructions

The finished paper refers to three equations, one table, two figures and four sections by number. A reference that does not resolve renders as “??”, so a search of each format for it is the check a reader would make by eye, done once: in the finished paper’s three formats, checked on 2026-11-18, it found none.

13.2 The paper

Ask your coding agent
Create whitepaper.qmd, a short technical white paper for clients and investors from outputs/ only: numbered sections (Introduction, Data, Method, Results, Limitations, Conclusion), the abstract written in the body rather than in the YAML, the definition of ROC AUC as a numbered equation, a results table and the ROC figure, each referred to in the text with @eq-, @tbl- and @fig-, vector figures for the PDF (`fig-format: svg`), and a guard on every sentence whose wording depends on the results. Formats html, typst and docx (the existing reference document); add it to the site's render list and listing with a description. Render it and check that no cross-reference shows "??".
Expect it to run

writes whitepaper.qmd · adds it to _quarto.yml and the home page’s listing · uv run quarto render whitepaper.qmd

Check it as its outside reader would. References resolve: search each output for “??”. Figures are vectors: in the PDF, zoom in on a figure’s labels; they stay sharp. Numbers agree: a number in the Results text equals the same number in the table. The abstract stands alone: someone who reads only the abstract knows what was evaluated, the headline result and its main limit.

13.3 References a reader can check

A reference list is a set of claims: this work exists, and it says what we say it says. An agent can produce a plausible reference that does not exist (Section 23.7), so the prompt requires opening each one, and allows only what was confirmed:

Ask your coding agent
Cite the dataset, Moro et al. (2014), Mitchell et al. (2019), and the papers behind ROC analysis, the bootstrap and calibration, from references.bib. Look each DOI up with the Crossref API, or DataCite's for the dataset, open it, and add only entries whose authors, title and year you could confirm. Download apa.csl from the official CSL styles repository, use it with `citeproc: true` for typst, render all three formats and check that their reference lists match.
Expect it to run

queries Crossref · edits references.bib · downloads csl/apa.csl · renders three formats

The project’s references.bib, which the paper shares with the model card, holds seven works, all of them cited by the paper, each one confirmed at its source on 2026-11-18:

Table 13.2: The project’s references, from the finished references.bib, and the documents that cite each.
Key Year DOI Cited by
moro2014bank 2014 10.24432/C5K306 paper, card
moro2014datadriven 2014 10.1016/j.dss.2014.03.001 paper, card
mitchell2019modelcards 2019 10.1145/3287560.3287596 paper, card
equalityact2010s4 2010 none: checked by hand at its source paper, card
fawcett2006roc 2006 10.1016/j.patrec.2005.10.010 paper
efron1979bootstrap 1979 10.1214/aos/1176344552 paper
niculescumizil2005calibration 2005 10.1145/1102351.1102430 paper

A citation style is a file. The Citation Style Language’s official repository holds thousands, APA and IEEE among them, and most journals’, each under a Creative Commons licence; download the one your readers expect and name it in csl:; in a site’s _quarto.yml, so that every document on the site cites alike, as the finished project does. Reference managers such as Zotero export the same .bib format, so an existing library can be the source, and Quarto’s visual editor can insert citations from a Zotero library directly. Either way, the check is the same: every entry was opened, and every claim it supports was read there.

WarningCommon pitfall

Traps met while building and testing the references. Without citeproc: true, the PDF hands citations to Typst’s own processor, which printed a different style and a second “Bibliography” heading. APA’s style lower-cases words in titles, so proper names such as “Bank Marketing” must be braced in the .bib to keep their capitals. The dataset’s DOI is registered with DataCite, not Crossref, and its record listed its authors wrongly, so it is cited as the repository’s own page gives it. One paper whose DOI resolved could not be opened at all; it is not cited, and the measure it introduced is defined in the text instead: cite what you have read. And in the PDF a conference’s abbreviated year, “ICML ’05”, came out with an opening quote, because Typst curls a straight apostrophe by its own rules. The finished paper leaves such abbreviated names out of its .bib; in the test run, a curled apostrophe in the .bib with the format written typst-smart instead of typst kept it right.

13.4 A check for every DOI

Opening every reference by hand is the first check; a script that repeats it before every release is the second, and the one that survives a colleague adding an entry in a hurry:

Ask your coding agent
Write scripts/check_refs.py: for every entry in references.bib with a DOI, look the record up (Crossref, or DataCite for a DataCite DOI) and fail if the DOI does not resolve or if the year, the first author's family name or the title disagree with the entry. Run it.

The script needs the network, so it is a check you run before publishing, not part of the render, which must work offline. Test it once on a deliberately broken copy of the .bib: a wrong year, a changed title and a DOI that does not exist should each fail it.

13.5 A house template for the PDF

Quarto writes a Typst PDF from a template made of named parts, template partials, and you can replace a part with your own. The one that styles the document is typst-show.typ; a replacement can give the paper a title block with the company’s logo and a label, a running header and page numbers, in the brand’s colours, which Quarto defines for it from _brand.yml:

Ask your coding agent
Give the PDF a house style: a Typst partial, templates/whitepaper/typst-show.typ, used from whitepaper.qmd's typst format with `template-partials`, that shows brand/logo.svg, the label "Technical white paper", the company and the date in a title block, and "page n of N" in the footer, in the brand's colours. Render the PDF and look at its first page.

The brand’s colours and logo reach the partial, but its name does not: in Quarto 1.10.20 only the brand’s typography becomes a template variable, so the finished paper names the company in a company: field of its own front matter. Render the PDF of the whole site, or delete what a single-page render with keep-typ leaves in the project folder: in the test run it wrote a site_libs/ folder and the .typ source beside the sources. One trap of Typst’s own: in a page-number pattern such as "1 of 1", letters are counters too, so a pattern written "page 1 of 1" printed “pbge” on the second page; keep words outside the pattern. Quarto 1.10.20 accepts only its own partial names (typst-show.typ, typst-template.typ, page.typ and four more); any other name stops the render. When a journal or a conference has its own format, use theirs instead of a house template: Quarto’s journal templates install with quarto use template quarto-journals/<name>, and the venue’s instructions come first.

Stuck for two minutes? Paste this into your agent. It backs up your work and brings the project to this point; then carry on from here.

Catch me up: follow ../quarto-workshop/checkpoints/18-eval-whitepaper/README.md
ImportantTry it

Write the paper, cite and check its references, and give the PDF the house template.

You’re done when every cross-reference resolves in the PDF, the Word file and the web page; the three reference lists match; check_refs.py reports no problems; and the PDF opens on the house title block.

Summary

  • A white paper is read without you and checked by strangers: numbered sections, cross-referenced figures, tables and equations, and references that exist.
  • Cross-references are labels (sec-, tbl-, fig-, eq-), and the render shows any that fail as “??”.
  • One CSL style file sets the citation style; citeproc: true makes a Typst PDF use it too.
  • Cite only what you have opened, and let a script confirm every DOI before each release.
  • A Typst template partial gives the PDF a house look from the brand; a journal’s template replaces it when a venue has one.

That completes the evaluation’s set: a report, a model card, a deck, a site and a white paper, all from one run of one script.

Further reading