✅ Key Features

• Plain text markup: Changes are visible in any text editor

• Language-agnostic: Works in org-mode, Markdown, LaTeX, and plain text

• Four mark types: Insertions, deletions, comments, and typo corrections

• Visual highlighting: Color-coded decorations for easy identification

• Quick navigation: Jump between marks with keyboard shortcuts

• Batch operations: Accept or reject all changes at once

• Hover actions: Quick accept/reject from hover tooltips

• Summary view: Overview of all changes in the document

✅ Use Cases

1. Document review: Mark suggested changes when reviewing a colleague's work

2. Collaborative editing: Track your edits when working on shared documents

3. Self-revision: Keep track of your own changes during editing sessions

4. Teaching and feedback: Provide inline suggestions to students or mentees

5. Version control: Complement Git commits with inline change tracking

✅ Universal Format (Recommended)

The universal format works in all document types:

@@+inserted text+@@       # Insertion
@@-deleted text-@@        # Deletion
@@>comment text<@@        # Comment
@@~old text|new text~@@   # Typo correction

✅ CriticMarkup Format (Alternative)

An alternative format inspired by CriticMarkup:

{++inserted text++}       # Insertion
{--deleted text--}        # Deletion
{>>comment text<<}        # Comment
{~~old text~>new text~~}  # Typo correction

Both formats are recognized and rendered identically. Choose whichever you prefer or is required by your workflow.

✅ Insertion

The quick brown fox @@+gracefully+@@ jumps over the lazy dog.

• Suggesting new content

• Adding missing words or phrases

• Inserting clarifications or examples

✅ Deletion

The quick brown @@-very-@@ fox jumps over the lazy dog.

• Removing redundant text

• Deleting incorrect information

• Suggesting text removal during review

✅ Comment

The results were statistically significant @@>verify p-value<@@.

• Asking questions about the text

• Leaving notes for the author

• Marking sections that need attention

• Providing context for other changes

✅ Typo Correction

The experment @@~experment|experiment~@@ was successful.

• Correcting spelling mistakes

• Fixing grammatical errors

• Suggesting better word choices

• Standardizing terminology

✅ Mark Insertion

1. With text selected: Wraps selection with insertion markup

2. Without selection: Prompts for text to insert

1. Select "quickly" in your text (or place cursor where text should be inserted)

2. Press `C-c e i'

3. If no selection, type the text to insert

4. Result: @@+quickly+@@

✅ Mark Deletion

• Requires text selection

• Wraps selected text with deletion markup

1. Select "very" in your text

2. Press `C-c e d'

3. Result: @@-very-@@

✅ Insert Comment

1. With text selected: Uses selection as comment text

2. Without selection: Prompts for comment

1. Place cursor at the relevant location

2. Press `C-c e c'

3. Type: "Check this citation"

4. Result: @@>Check this citation<@@

✅ Mark Typo Correction

• Requires text selection (the incorrect text)

• Prompts for the correct text

• Creates a typo mark showing old→new

1. Select "teh" in your text

2. Press `C-c e t'

3. Type: "the"

4. Result: @@`teh|the'@@

✅ Accept Edit Mark

Accepts the editmark at the cursor position:

• Insertion: Keeps the inserted text, removes markup (@@+text+@@ → text)

• Deletion: Removes the deleted text entirely (@@-text-@@ → empty)

• Comment: Removes the comment (@@>text<@@ → empty)

• Typo: Applies the correction (@@`old|new'@@` → 'new)

Before: The quick @@+brown+@@ fox
After:  The quick brown fox

✅ Reject Edit Mark

Rejects the editmark at the cursor position:

• Insertion: Removes the inserted text (@@+text+@@ → empty)

• Deletion: Keeps the original text (@@-text-@@ → text)

• Comment: Removes the comment (@@>text<@@ → empty)

• Typo: Keeps the original text (@@`old|new'@@` → 'old)

Before: The quick @@+brown+@@ fox
After:  The quick fox

✅ Accept All Edit Marks

Accepts all editmarks in the current document:

1. Shows confirmation dialog with count

2. Processes all marks from bottom to top

3. Displays success message

✅ Reject All Edit Marks

Rejects all editmarks in the current document:

1. Shows confirmation dialog with count

2. Processes all marks from bottom to top

3. Displays success message

✅ Hover Actions

Position your cursor over any editmark to see a hover tooltip with:

• Mark type and content

• Quick action links to accept or reject

• For typos: Shows old → new transformation

This provides a quick way to review and act on individual changes without remembering keybindings.

✅ Next Edit Mark

Moves the cursor to the next editmark in the document:

• Wraps around to the first mark if at the end

• Centers the mark in the viewport

• Useful for systematic review

✅ Previous Edit Mark

Moves the cursor to the previous editmark:

• Wraps around to the last mark if at the beginning

• Centers the mark in the viewport

✅ Keyboard Navigation Pattern

The bracket keys ([ and ]) create an intuitive navigation pattern:

• C-c e ] → next (forward, like closing bracket points right)

• C-c e [ → previous (backward, like opening bracket points left)

Insertion Commands

Deletion Commands

Comment Commands

Typo Correction Commands

Review Commands

Navigation Commands

Utility Commands

Workflow 1: Peer Review

1. Open the document in VS Code

2. Read through and identify areas needing changes

3. Mark suggestions:

4. Add typo corrections:

5. Save the document and send back to colleague

6. Colleague reviews using C-c e ] to navigate between marks

7. Colleague processes each mark:

8. Save final version with all changes resolved

Workflow 2: Self-Editing

1. Enable editmarks mode (always on - no toggle needed)

2. As you edit, use editmarks instead of direct changes:

3. Take a break - changes are preserved in plain text

4. Review later:

5. Process systematically:

6. Commit to version control with clear change history

Workflow 3: Collaborative Writing

1. Author A makes initial draft

2. Author B checks out the branch and adds suggestions:

3. Author C adds more changes:

4. Authors meet to review:

5. Accept/reject collaboratively

6. Commit final version to Git with all changes incorporated

Workflow 4: Student Feedback

1. Open student's submission

2. Read through once without marking

3. Second pass - mark issues:

4. Add pedagogical comments:

5. Generate summary report:

6. Student processes feedback:

Workflow 5: Document Review Cycle

The project will @@+likely+@@ be completed @@-on time-@@ @@+ahead of schedule+@@.
@@>Reviewer: Source for this claim?<@@

The project will @@+likely+@@ be completed @@+ahead of schedule+@@.
@@>Author: Added reference below. See Smith et al. 2025<@@
[ref added here]

1. Reviewer opens document

2. Presses `C-c e s' to see all outstanding marks

3. Navigates with C-c e ] through each change

4. Presses `C-c e a' to accept all approved changes

5. Final document is clean and ready for publication

✅ Do's

1. Use descriptive comments: Instead of @@>fix this<@@, write @@>fix grammar: subject-verb agreement<@@

2. Be specific with insertions: Show exactly what you're suggesting

3. One change per mark: Don't combine multiple edits in one mark

4. Review systematically: Use navigation commands to ensure you don't miss any marks

5. Preserve marks in Git: Commit documents with editmarks to track review history

6. Use hover tooltips: Quick way to remind yourself what each mark does

✅ Don'ts

1. Don't nest editmarks: Avoid @@+text @@-with-@@ nesting+@@ - it's confusing

2. Don't mix formats randomly: Pick either universal or CriticMarkup and stick with it

3. Don't leave marks indefinitely: Process them regularly to keep documents clean

4. Don't delete marks manually: Use accept/reject commands to ensure proper processing

5. Don't use for version control: Editmarks complement Git but don't replace it

✅ Tips

• Quick review: Use C-c e s at the start of each editing session to see pending changes

• Batch processing: For documents with many trivial changes, use "Accept All" after review

• Comments as TODO: Use comment marks as inline TODO items during writing

• Color awareness: Learn to recognize mark types by color for faster visual scanning

• Git integration: Create commits after processing editmarks with descriptive messages

• Keyboard efficiency: The navigation keys ([ and ]) combined with a/r enable fast review

✅ Source Blocks

Editmarks work inside source blocks (although they likely break the code unless you use them in comments.):

def calculate(x):
    return x * @@+2+@@ @@-3-@@  @@>why change the multiplier?<@@

This is useful when reviewing code snippets in documentation or educational materials.

✅ Tables

Use editmarks in table cells:

✅ Export Compatibility

Editmarks are fully supported in HTML, LaTeX, and PDF exports. The export behavior is controlled by the scimax.export.editmarkMode setting.

\editins{inserted text}           % Green underlined text
\editdel{deleted text}            % Red strikethrough text
\editcomment{comment text}        % Orange italic text in brackets
\edittypo{old text}{new text}     % Old crossed out, new inserted

{
  "scimax.export.editmarkMode": "show"
}

✅ Version Control

Editmarks are perfect for version control workflows:

# Add document with editmarks
git add manuscript.org

# Commit with descriptive message
git commit -m "Add reviewer feedback as editmarks"

# Later, after processing
git add manuscript.org
git commit -m "Incorporate reviewer suggestions"

The diff shows both the markup and the final changes, providing complete review history.

✅ Editmarks Not Showing

1. Check that you're in a supported file (any text file works)

2. Reload window: C-S-P → "Developer: Reload Window"

3. Verify syntax: Ensure markup is exactly correct (e.g., @@+text+@@ not @@+ text +@@)

✅ Navigation Not Working

1. Verify editmarks exist: Press C-c e s to see summary

2. Ensure cursor is in the editor window

3. Check keybinding conflicts: File → Preferences → Keyboard Shortcuts

Accept/Reject Not Working

1. Position cursor inside the editmark (between the markup symbols)

2. Hover over the mark to see the tooltip - if visible, cursor is positioned correctly

3. Check that the editmark syntax is valid

✅ Nested Marks Issue

✅ Performance with Many Marks

1. Process marks in batches (accept/reject groups of related changes)

2. Use "Accept All" or "Reject All" for bulk processing

3. Split large documents into smaller files

Q: Can I customize the colors?

A: Currently, colors are fixed (green for insertion, red for deletion, yellow for comments, orange for typos). Custom theme support may be added in future versions.

Q: Do editmarks work in any file type?

A: Yes! Editmarks work in any text file: .org, .md, .tex, .txt, .py, etc. The markup is plain text.

Q: Can I export documents with editmarks?

A: Yes! Editmarks are fully supported in HTML, LaTeX, and PDF exports. Use the scimax.export.editmarkMode setting to control how they appear:

• show: Visual markup with colors (default)

• accept: Apply all changes automatically

• reject: Revert all changes

• hide: Remove editmarks silently

Q: How do I see who made which mark?

A: Editmarks don't automatically track authors. Add author names manually in comments:

@@>(Author: John Doe) This needs clarification<@@

Q: Can I use editmarks with Word documents?

A: No, editmarks require plain text files. Convert Word documents to Markdown or use Word's built-in track changes.

Q: Do editmarks interfere with syntax highlighting?

A: No, they're implemented as decorations that overlay the text without modifying syntax highlighting.

Q: Can I undo an accept/reject action?

A: Yes, use VS Code's regular undo (C-z) immediately after accepting or rejecting a mark.

Q: Are editmarks saved with the file?

A: Yes! Editmarks are plain text markup, so they're saved as part of the document content.

Q: Can I search for editmarks?

A: Yes, use regular search (C-f) for @@+ or {++ to find all insertions, etc. Or use C-c e s for the summary view.