6  Proofreading comments and annotations

6.1 Collaborative comments

6.1.1 Configuration in _quarto.yml

The quarto-proofread-comments extension (folder _extensions/proofread-comments/) is configured in _quarto.yml, via the quarto-proofread-comments: key placed under the extensions: block . Full extension documentation: zinc75.github.io/quarto-proofread-comments

Abbé Grégoire

You will need to walk me through your various YAML files at our next progress meeting.

extensions:
  quarto-proofread-comments:
    enabled: true
    reviewers:
      eb:
        name: "Eric Bavu"
      ag:
        name: "Abbé Grégoire"
      # Colors auto-assigned from Bootstrap 5 palette; override if needed:
      # nc:
      #   name: "Nicolas Conté"
      #   color_html: "#198754"
      #   color_latex: "green!30"

6.1.2 Comment syntax

The extension uses Pandoc span syntax inside brackets. An empty span [] creates an inserted comment (no highlighted text); a non-empty span highlights the text and attaches the note to it.

[]{.comment by="ag" remark="Rephrase this sentence, it is too long."}
[]{.comment by="eb" type="todo" remark="Add a figure illustrating this point."}
[]{.comment by="ag" type="note" remark="See also Bringhurst 2004, §2.4."}
[]{.comment by="ag" type="question" remark="Is this result reproducible on another dataset?"}
[highlighted text]{.comment by="ag" remark="This passage deserves a rewrite."}
[]{.comment by="eb" inline="true" remark="An inline aside, inserted in the text flow."}

The four available types are comment (default), todo, note, and question.

Rendered in context:

Here is a sentence with a comment from the thesis supervisor (who added it directly in the .qmd file, because he is not shy about it!).

Abbé Grégoire

This is a comment, to show that I too — Abbé Grégoire — am perfectly capable of editing a Quarto Markdown file myself!

These comments are visible only if the quarto-proofread-comments option is set to enabled: true in the yaml file — which is the case for this documentation.

Eric Bavu

Remember to set this option to false before submitting the finalised manuscript to the doctoral school and the jury!

It is also possible to highlight a passage and attach a margin note to it — the highlighted text becomes the visual link between the passage and the annotation.

Abbé Grégoire

See Knuth 1984, chapter 12 — it would really be worth adding a discussion of this work here to show off all your knowledge of the existing literature, young apprentice.

Noteinline="true": remark inserted in the text flow

With inline="true", the remark is inserted directly in the running text — in both HTML and PDF — as a compact coloured badge, with no block or line break. This is the extension’s inline_style: "flow" mode (the default). Useful for short asides slipped mid-sentence without disrupting the paragraph layout.

Astucewide_margins: true is the default

For margin notes, extensions.quarto-proofread-comments.wide_margins: true is the default value. The paper is widened outward by a dedicated strip (width adjustable via extra_margin) where annotations display comfortably, with a grey background that alternates by page parity (outer side, binding preserved).

Per-chapter scoping. The widening and the grey strip appear only in the chapters that actually contain comments: a chapter without annotations stays at standard A4, with no grey strip. The template detects the relevant chapters automatically (by scanning the book’s source files), so the commented areas stand out in a proofreading PDF without needlessly widening the whole document. Acceptable cosmetic side effect: at the boundary between a wide chapter and an A4 chapter, a blank spacing page (\cleardoublepage) may inherit the previous width — irrelevant for the final deposit, where comments are off and every page is back to A4.

Set wide_margins: false to keep standard A4 format: notes are placed in the 2 cm outer margin. The content layout (text block) is strictly identical regardless of the wide_margins value, and whether comments are enabled or not — only the margin annotation zone changes.

ImportantDisable comments before final submission

Before submitting the thesis to the doctoral school and depositing it on theses.fr, set extensions.quarto-proofread-comments.enabled: false in _quarto.yml. Annotations must not appear in the official archived version.

6.2 Web annotations with Hypothesis (opt-in)

For remote proofreading, the HTML output can be enhanced with web annotations via Hypothesis. Supervisors and reviewers select text in the browser and add comments without touching the source files. Annotations are stored on Hypothesis servers and tied to the page URL — they persist across renders as long as the URL stays stable (GitHub Pages deployment recommended).

To enable, uncomment the following block in _quarto.yml:

format:
  cnam-thesis-html:
    comments:
      hypothesis:
        theme: clean   # clean = discreet ; classic = sidebar always visible

Then create a private group on hypothes.is and share the invite link with your reviewers. Hypothesis is disabled by default in all profiles.