A Lightweight Peer Review Workflow with Quarto and Hypothesis

  • ◀
    Soil:
    By: Alfie Chadwick Date: March 13, 2026 Bee
    ▶
    Seeds:

    • If you write in Quarto, you’ve probably run into this: the writing is going well, the document renders beautifully, the code and prose are living together exactly as they should — and then you need feedback from a co-author. Suddenly you’re choosing between emailing a PDF and hoping for coherent reply-chain comments, pasting everything into Google Docs and losing all your formatting, or convincing a non-technical collaborator to use Overleaf. None of these are good options. All of them involve leaving the tool you’re actually working in.

    Quarto doesn’t have a great collaboration story yet. It’s a fantastic tool for reproducible, well-formatted academic writing, but the assumption seems to be that once you’re done writing you export to something else and collaborate there. That’s a real gap, and it’s worth trying to fill it without abandoning the workflow entirely.

    The harder version of this problem is mixed teams. Not everyone you work with wants to annotate in a browser or pull a repo. Some co-authors just want a printed PDF with margin notes. Any solution has to at least acknowledge that reality, even if it can’t fully solve it.

    I’ve been thinking about this for a while, and I’ve landed on something that works well enough to write up.

    The Core Idea

    The setup is simple: render the Quarto document to HTML, embed Hypothesis directly in the output, and host it at a secret URL on my Netlify site. Collaborators get a link, open it in any browser, and can annotate inline without installing anything. I can push updates whenever I want, and the annotations persist as long as the URL stays stable.

    The “secret URL” is just a UUID — something like alfiechadwick.com/a3f9b2c1-.../. It’s not linked from anywhere on the site, so Google won’t find it. It’s not real access control, but it’s good enough for a trusted group of collaborators. When the review round is done, I unpublish it and the link goes dead.

    Why Not Just Share a PDF?

    The obvious alternative is to share a PDF and have people annotate that. Hypothesis works on PDFs too, and I used to plan to go that route. The problem is that Hypothesis used to offer a proxy service — via.hypothes.is — that would wrap any URL and inject the annotation sidebar. That service was shut down to public use in early 2026. Without it, collaborators need the browser extension installed, which is one more thing to ask people to do.

    Embedding Hypothesis directly in the HTML sidesteps this entirely. The script tag is injected at render time, so the sidebar just appears when you open the page.

    The Implementation

    I wrote a small Python script — quarto_publish.py — that handles the whole thing. It maintains a registry mapping .qmd files to their secret UUIDs, so the same document always gets the same URL across republishes. Running it is a single command from Overseer:

    • Publish for Review — renders the current buffer to HTML (with Hypothesis embedded) and PDF (using whatever format the frontmatter specifies — in my case ccr-pdf), copies both into _site/<uuid>/, and prints the shareable URL.
    • Unpublish Review — removes the entry from the registry and deletes the directory.
    • List Review Docs — shows everything currently out for review with its URL.

    The PDF is included alongside the HTML so collaborators can download it if they want to read offline — useful for the co-authors who’d rather print it out. Quarto’s HTML output automatically generates an “Other Formats” link to it in the sidebar. The .qmd and .tex source files are also served from the same directory for anyone who wants to see exactly what generated a particular table or figure.

    What This Doesn’t Do

    Hypothesis anchors annotations to specific text passages. If you push an update that rewrites a section someone has annotated, their comment becomes an orphan — still visible in Hypothesis, but no longer attached to any text. The mitigation is to be deliberate about when you push updates: treat each publish as the start of a new review round and don’t rewrite annotated sections mid-cycle.

    The mixed-team problem is also only partially solved. For collaborators comfortable opening a URL and typing in a browser sidebar, this works well. For those who aren’t, the PDF download is a reasonable fallback. But there’s no clean answer for the co-author who wants tracked changes in Word — that still requires a separate export and a separate workflow.

    The Result

    For my purposes, this hits the right balance. I stay in Quarto end-to-end, collaborators don’t need to install anything, and I have full control over what’s published and when. Until Quarto addresses collaboration natively, a bit of scripting goes a long way.