Markup Types
kaicrit supports all five CriticMarkup types. Each type is rendered with a distinct color; marker characters are visually de-emphasized.
In the editor, every change is also mirrored as a colored mark on the overview ruler (the scrollbar lane on the right), giving an at-a-glance map of where changes sit in the document. The ruler marks reuse the same kaicrit.* colors as the inline decorations (see Colors); the dimmed marker characters themselves are not shown on the ruler.
Syntax
| Type | Syntax | Purpose |
|---|---|---|
| Deletion | {--deleted text--} |
Mark text for removal |
| Addition | {++added text++} |
Mark text for insertion |
| Substitution | {~~old~>new~~} |
Mark a replacement pair (the ~> arrow is required) |
| Highlight | {==highlighted text==} |
Mark text for attention |
| Comment | {>>comment text<<} |
Inline annotation |
Accept / Reject Semantics
Accepting or rejecting a change strips the markup and resolves the content:
| Type | Accept | Reject |
|---|---|---|
Deletion {--T--} |
removes T |
keeps T |
Addition {++T++} |
keeps T |
removes T |
Substitution {~~O~>N~~} |
keeps N |
keeps O |
Highlight {==T==} |
keeps T (strips markers) |
keeps T (strips markers) |
Comment {>>T<<} |
removes entirely | removes entirely |
Accept All / Reject All apply all resolutions atomically in a single edit.
Whitespace tidy-up on resolve
A change that resolves to nothing — a comment (on both accept and reject), an
accepted deletion, or a rejected addition — can leave an orphaned whitespace
artifact when it was surrounded by whitespace: a stray double space if it sat between
two spaces (the {--quick--} brown → accept → the brown), or an empty blank line if
it sat alone on its own line (the now-empty line is removed instead of left blank).
The setting kaicrit.edit.collapseWhitespaceOnResolve (default true, document-scoped)
controls this tidy-up. Only spaces/tabs and a single adjacent line break are ever removed,
and only for changes that collapse to empty — substitutions, highlights, and
reject-of-deletion stay exact. Set it to false for strictly literal resolution, where
every replacement is exactly the marker's accept/reject text (matching the original
CriticMarkup semantics; the Compare round-trip is exact regardless).
Note on substitution syntax: the
~>separator is mandatory. An arrow-less{~~text~~}is not a valid CriticMarkup marker (it is neither a substitution nor a deletion, per the CriticMarkup spec). Both the editor and the Markdown preview ignore it: it is left as plain text rather than being rendered as a change. Use{--text--}to mark a deletion.Inserting a substitution: Insert Substitution wraps the current selection as the "old" side (
{~~selection~>~~}) and parks the cursor before~~}so you type the replacement. A substitution must replace existing text, so with no selection the command declines (a short status-bar hint asks you to select the text to replace first) rather than inserting an empty pair — an empty "old" side would just be a plain addition ({~~~>new~~}≡{++new++}). Use Insert Addition to add text from scratch.
Inline-Aktionen
Für jede Änderung bietet kaicrit klickbare Accept · Reject-Aktionen. Ein Klick
löst genau diese Änderung auf – dieselbe Logik wie bei den Tastenkürzeln, nur
ohne sie kennen zu müssen. Wo die Aktionen erscheinen, steuert die Einstellung
kaicrit.edit.changeActions:
hover(Standard) – die Aktionen erscheinen nur im Hover-Tooltip über einer Änderung. Der Tooltip ist an die Änderung gebunden, also ist immer klar, welche Änderung aufgelöst wird, und der Text bleibt frei von Dauer-Einblendungen.codeLens– eine dauerhafte CodeLens-Zeile über jeder Änderung: Typ-Symbol- gekürzte Inhaltsvorschau (
☰ "impossible f…", Klick springt zur Änderung), gefolgt von ✓ / ✕ als Icons. So bleiben auch zwei Änderungen in einer Zeile unterscheidbar. off– keine Inline-Aktionen; stattdessen Tastenkürzel, Statusleiste oder die Changes-Sidebar nutzen.
Kommentar-Metadaten (Autor & Datum)
Kommentare können optional mit einem Autor und/oder einem ISO-Datum beginnen, durch einen Doppelpunkt vom Kommentartext getrennt:
{>>@kai 2026-05-31: needs a source<<}
{>>@kai: looks good<<}
{>>2026-05-31: revisit later<<}
Das Format lautet [@autor] [JJJJ-MM-TT]: – beide Teile sind optional, aber
mindestens einer muss vorhanden und von einem Doppelpunkt gefolgt sein, damit der
Vorspann als Metadaten gilt.
Die Konvention ist rückwärtskompatibel: Ein Kommentar ohne diesen Vorspann
verhält sich exakt wie bisher. Auch ein gewöhnlicher Doppelpunkt im Fließtext
({>>Note: siehe oben<<}) wird nicht als Metadaten interpretiert, da kein
@autor und kein Datum davorstehen.
Sind Metadaten vorhanden, werden Autor/Datum
- im Editor als Hover über dem Kommentar angezeigt, und
- im Markdown-Preview dem Kommentartext als hervorgehobener Präfix vorangestellt
(
.critic-comment-meta).
Accept/Reject entfernt den Kommentar weiterhin vollständig (Metadaten inklusive).
Beim Einfügen eines Kommentars (Alt+K Alt+C) wird @autor heute: vorbefüllt. Der
Autor stammt aus der Einstellung kaicrit.edit.commentAuthor; ist sie leer, greift
kaicrit auf git config user.name des Repositories zurück.
| Einstellung | Standard | Wirkung |
|---|---|---|
kaicrit.edit.commentMetadata |
true |
Autor/Datum-Konvention erkennen (Hover, Preview, Vorbefüllung). Bei false sind Kommentare reiner Text. |
kaicrit.edit.commentAuthor |
"" |
Beim Einfügen vorbefüllter Autor. Leer ⇒ Rückgriff auf git config user.name. |
Colors
Each change type uses a configurable decoration color. Defaults follow the active theme; override any color via workbench.colorCustomizations in settings.json:
"workbench.colorCustomizations": {
"kaicrit.highlightBackground": "#ffe066",
"kaicrit.deletionForeground": "#cc0000"
}
| Color ID | Default | Applied to |
|---|---|---|
kaicrit.deletionForeground |
editorError.foreground |
Deletion text |
kaicrit.additionForeground |
gitDecoration.addedResourceForeground |
Addition text |
kaicrit.substitutionOldForeground |
editorError.foreground |
Substitution — removed part |
kaicrit.substitutionNewForeground |
gitDecoration.addedResourceForeground |
Substitution — inserted part |
kaicrit.highlightBackground |
#ffff00 |
Highlight background |
kaicrit.highlightForeground |
#333333 |
Highlight text |
kaicrit.commentBackground |
#e0e0e0 |
Comment background |
kaicrit.commentForeground |
#555555 |
Comment text |
The same colors also tint the per-type counts in the status bar and the type icons in the Changes sidebar, so a customization carries through every surface. Deletion, addition, and substitution use their (new-side) foreground there; highlight and comment use their background color, whose foregrounds are grays tuned to sit on those backgrounds and would be hard to see standing alone.
Status bar
When the active editor contains CriticMarkup, a status bar entry summarizes the open changes by type, each count tinted in its type's configured color:
⊟3 ⊞5 ⇄2 ☰1 💬4
| Glyph | Type |
|---|---|
⊟ |
Deletions |
⊞ |
Additions |
⇄ |
Substitutions |
☰ |
Highlights |
💬 |
Comments |
The counts update live as you type, insert, or accept/reject changes. The entry is hidden when the active editor has no changes, and clicking it jumps to the first change (kaicrit.firstChange).