docs / beta

Margin notesbeta

Reageer op elk lokaal Markdown-document zoals je op een pull request zou reageren — alleen wonen de comments in het bestand zelf, als gewone HTML-comments die buiten de gerenderde pagina blijven. Gebouwd voor één loop in het bijzonder: een agent schrijft een document voor je, jij leest het in PullMark en laat gaandeweg notities achter, en dan geef je het bestand terug met "verwerk de notities en verwijder ze als je ermee klaar bent." De agentspagina loopt die hele loop door, met screenshots en al.

Gebruiken in PullMark

Lees je dit op de Mac waar PullMark (0.28.1+) is geïnstalleerd? Spring direct naar de margin-notes-schakelaar.

• Ze staan standaard aan — margin notes zijn een experimentele functie in beta die aan wordt geleverd (sinds 0.35). De eerste keer dat je ernaar grijpt — het notitieballonnetje bij hover, ⌥⌘M, of Bewerk / Verwijder op een notitie die iemand voor je achterliet — introduceert PullMark de functie: wat notities zijn, een Kopieer-knop om je agent op te leiden, en een Zet uit-knop als het niets voor je is. De schakelaar staat in Instellingen → Experimenteel en gaat alleen over het zélf schrijven; een document dat al notities bevat toont zijn ballonnetjes hoe dan ook (alleen-lezen), zodat een bestand met aantekeningen van een teamgenoot of een agent nooit stilzwijgend leeg rendert.
• Een notitie toevoegen — hover over een blok in een lokaal document en klik op het ballonnetje in de kantlijn (hetzelfde gebaar als reageren op een PR). In een lijst mikt het ballonnetje op het item dat je aanwijst, in een tabel op de rij — een subtiele tint laat precies zien waar de notitie aan komt te hangen. Selecteer eerst tekst en de notitie opent met de selectie geciteerd — zo wijs je een zin aan in plaats van een alinea. ⌥⌘M noteert bij het blok dat je leest; Wijzig → Margin note over bestand… laat bovenaan een notitie over het hele document achter.
• Schrijf Markdown — vet, code-spans, fenced code, links, lijsten; ⌘↩ slaat op. Elke save is één bewerking in het bestand (terug te draaien met Archief → Draai laatste bewerking terug).
• Bewerk / Verwijder — hover over een ballonnetje voor de bijbehorende acties. Een notitie verwijderen is hoe je haar afhandelt: geen status, geen archief — een verwerkte notitie is een afwezige notitie.
• De chip — rijen in Geopende bestanden dragen een chip met het aantal notities zolang een document ze nog bevat. Hij leeft mee: terwijl een agent het bestand doorwerkt en notities verwijdert, loopt de teller terug en verdwijnen de ballonnetjes voor je ogen.
• Overal elders — notities renderen alleen-lezen in doorbladerde GitHub-bestanden, verschijnen nooit bij afdrukken, in een PDF/HTML-export of in Quick Look, en Weergave → Verberg margin notes maakt de pagina leeg wanneer je schoon wilt lezen.
• Je ondertekening — notities worden standaard ondertekend met @je-github-login; je verandert dat onder de schakelaar van de functie zelf in Instellingen → Experimenteel.

Het formaat

Een margin note is een HTML-comment met het sleutelwoord note en een auteurstag, op een eigen regel na het blok waar hij over gaat:

Requests retry three times with exponential backoff.

<!-- note @josh: Section 2 says five times. Which is it? -->

Een notitie over één lijstitem woont ín het item — ingesprongen tot de inhoud van het item, strak aangesloten, zodat de lijst heel blijft:

- First point
  <!-- note @josh: too vague — name the metric -->
- Second point

Langere notities zetten de sluitmarkering op een eigen regel; de body is volwaardige Markdown, lege regels en fenced code inbegrepen:

<!-- note @josh:
This contradicts the design doc. Either reconcile them or
drop this section.

```suggestion
Requests retry five times with exponential backoff.
```
-->

De volledige grammatica:

Omdat Markdown-renderers HTML-comments overslaan, rendert een bestand met notities erin schoon op GitHub, in editors en in elke andere tool — de notities reizen mee in de bron zonder de pagina te vervuilen. PullMark is de mooie client voor een formaat dat overal werkt.

Voor agents

De overdracht vergt geen protocol: agents lezen bestanden, en de notities staan in het bestand, fysiek naast de tekst waar ze over gaan. Plak dit in je CLAUDE.md / AGENTS.md — Instellingen → Experimenteel heeft een Kopieer-knop met dezelfde tekst (of zeg het gewoon):

## Margin notes

Markdown files may contain review notes as HTML comments:
`<!-- note @name: comment -->` (possibly multi-line, closing
with `-->` on its own line). Each note sits directly after the
passage it's about; a note above the first heading is about the
whole document. `--\>` inside a note means a literal `-->`.

When asked to address notes: work through each one, apply or
answer it, and DELETE the note (with its surrounding blank line)
once addressed. To reply or ask instead, leave your own note in
the same format below the original, signed with your own @name.
Don't add notes to code examples inside fenced blocks.

A note about one list item sits inside that item — directly after
the item's last line, indented to the item's content, with no
blank lines around it. Keep (or delete) the whole indented
comment; its indentation is what ties it to the item.

De convergentieloop volgt uit het formaat: overgebleven ballonnetjes zijn overgebleven werk, en een leeg bestand is een afgeronde review. Mogen notities nooit een pull request bereiken, dan is een CI-check één regel — grep -rn '<!-- note @' docs/ && exit 1.

Waarom het beta is

De mechaniek heeft zich bewezen — het formaat heeft sinds de release geen incompatibele wijziging nodig gehad, en daarom is het uit alpha geslaagd. Volgens het betacontract doen we nu serieus ons best om de grammatica en het gedrag compatibel te houden tussen versies, en de functie slaagt waarschijnlijk helemaal uit Experimenteel. Wat nog moet uitkristalliseren is het oppervlak eromheen: namen, affordances, en hoe ver de workflow zich laat uitbreiden buiten de agent-reviewloop waarin hij is ontworpen. De releasenotes melden precies wat er verandert, als er iets verandert. Feedback welkom.