New Package! - Simply Annotate: A Lightweight Annotation System

Yes thats right, yet another annotation system!, in this case it is a lightweight annotation system for Emacs that allows you to add persistent notes to any text file without modifying the original content.

https://melpa.org/#/simply-annotate https://github.com/captainflasmr/simply-annotate

Still not convinced it is any different to any other note taking package in Emacs given that previous generic sparse description? Well I shall do my best to explain my own note taking ideas. Of course this is also just a pet project to continue to learn elisp, so there is that too :)

I developed this package to fill my own perceived gap in the existing Emacs note-taking ecosystem. Although annotate.el comes close to what I needed, I wanted a simplified version and something with a few workflow adjustments that better suit my note taking preferences. The result is a lightweight alternative that handles annotations the way I have always wanted them to work.

The main functional aspects that I felt were important to me that generally differ from other existing Emacs annotation packages are:

• Header-line status display with keybinding reminders
• Simple intuitive workflow (hopefully)
• Multiple display styles (highlight, fringe indicators, or both)
• Annotation editing via a dedicated buffer
• Lightweight (if possible <1000 lines - [UPDATE], no its not possible, lets try <2000 lines!)
• Multi-purpose key to show/edit/toggle annotations
• Dedicated annotation buffer that can pop in and out
• Quickly step through annotations with M-n and M-p
• Buffer summary of annotations in grep-mode format
• Quickly browse through all annotated files using completing-read
• Smart action command that adapts based on context
• Threading conversations for each annotation

See https://github.com/captainflasmr/simply-annotate/blob/main/docs/simply-annotate.org for the manual!

Quick Demo Video

Open this file and open the simply-annotate.el file

• highlight some regions and put in some annotation comments

• step through annotation comments

• show summary

• delete some annotations

Go to the directory level and now browse the 2 files

Whats New

<2025-07-03 Thu> 0.6.0

A little refactoring and tidying up.

<2025-06-29 Sun> 0.5.1

• Raw sexp editing: Edit annotation data structures directly as Elisp for complete control
• Advanced editing capabilities: Full access to thread metadata, status, priority, and comments

Updated Key Bindings:

• M-s e: Edit annotation as raw Elisp sexp

<2025-06-20 Fri> 0.5.0

• Threading system: Add replies to annotations for conversations
• Status management: Track progress (open, in-progress, resolved, closed)
• Priority levels: Set importance (low, normal, high, critical)
• Multi-author support: Configure team members for collaboration
• Tag system: Organize with hashtags (#review, #bug, #question)
• Org-mode export: Convert threads to structured TODO items
• Enhanced display: Thread info in headers and lists
• Author management: Flexible prompting modes and author changes

New Key Bindings:

• M-s r: Add reply to annotation
• M-s s: Set status
• M-s p: Set priority
• M-s t: Add tag
• M-s a: Change author
• M-s o: Export to org-mode

<2025-06-20 Fri> 0.0.1

• Basic annotation functionality
• Persistent storage
• Navigation commands
• Org-mode export
• Customizable highlighting

Installation

MELPA (Recommended)

(use-package simply-annotate
  :bind ("C-c A" . simply-annotate-mode))

Manual Installation

1. Download simply-annotate.el
2. Place it in your Emacs load-path
3. Add to your configuration:

(require 'simply-annotate)
(global-set-key (kbd "C-c A") simply-annotate-mode)

Quick Start

1. Open any file
2. Enable annotation mode: M-x simply-annotate-mode
3. Select/mark text and press M-s j to create your first annotation
4. Create some more annotations
5. Navigate with M-n (next) and M-p (previous)
6. Add replies: Press M-s r on any annotation to reply
7. Set status: Press M-s s to track progress (open/resolved/etc.)
8. Advanced editing: Press M-s e to edit annotation data structure directly

Usage

Enabling Annotation Mode

M-x simply-annotate-mode

Or bind to a convenient key:

(global-set-key (kbd "C-c A") 'simply-annotate-mode)

Creating Annotations

Simple

The M-s j command (simply-annotate-smart-action) is context-aware:

1. With region selected: Creates new annotation or edits existing one
2. On annotated text: Toggles annotation buffer visibility
3. With prefix (C-u M-s j): Forces edit mode on existing annotation
4. Elsewhere: Creates annotation for current line
5. Enter your annotation text in the dedicated buffer
6. Save with C-c C-c

Advanced Editing

Raw Sexp Editing

For complete control over annotation data structures:

1. Place cursor on any annotation
2. Press M-s e to open the raw sexp editor
3. Edit the Elisp data structure directly:
   • Modify thread metadata (status, priority, tags)
   • Edit comment text and timestamps
   • Add/remove/reorder comments
   • Change author information
4. Save with C-c C-c or cancel with C-c C-k

Example sexp structure:

((id . "thread-123456")
 (created . "2025-06-29T10:30:00")
 (status . "open")
 (priority . "high")
 (tags . ("bug" "critical"))
 (comments . (((author . "John Doe")
               (timestamp . "2025-06-29T10:30:00")
               (text . "Found a critical bug here")
               (type . "comment"))
              ((author . "Jane Smith")
               (timestamp . "2025-06-29T11:15:00")
               (text . "I can reproduce this issue")
               (type . "reply")))))

Threading & Collaboration

Adding Replies

1. Place cursor on any annotation
2. Press M-s r to add a reply
3. Enter your response
4. The annotation becomes a threaded conversation

Status Management

• Press M-s s to set status: open, in-progress, resolved, closed
• Press M-s p to set priority: low, normal, high, critical
• Press M-s t to add tags like #review, #bug, #question

Author Management

Configure for single-user or team workflows:

;; Single user (default behavior)
(setq simply-annotate-prompt-for-author nil)

;; Team collaboration
(setq simply-annotate-author-list '("John Doe" "Jane Smith" "Bob Wilson"))
(setq simply-annotate-prompt-for-author 'threads-only)  ; Prompt only for replies
(setq simply-annotate-remember-author-per-file t)       ; Remember per file

Available prompting modes:

• nil: Never prompt (single-user mode)
• 'first-only: Prompt once per session
• 'always: Prompt for every annotation
• 'threads-only: Prompt only for thread replies (great for reviews)

Author Commands

• M-s a: Change author of existing annotation/comment

Display Styles

Simply Annotate supports three display styles:

• Highlight: Traditional background highlighting (default)
• Fringe: Shows indicators in the left fringe
• Both: Combines highlighting with fringe indicators

Change styles with M-s ] or customize simply-annotate-display-style.

Viewing Annotations

When simply-annotate-mode is active:

• Annotated text is displayed according to your chosen style
• The header line shows annotation count, status info, and available commands
• * Thread info*: Header shows [OPEN/HIGH:3] for status, priority, and comment count
• Moving to annotated text shows annotation details in the header
• Press M-s j on annotated text to view/edit in detail

Navigation

Managing Annotations

Creating

• Select/mark some text
• Press M-s j to open the annotation buffer
• Make your changes
• Save with C-c C-c

Editing

Standard Editing:

• Place cursor on annotated text
• Press C-u M-s j to open the annotation buffer
• Make your changes
• Save with C-c C-c

Advanced Sexp Editing:

• Place cursor on annotated text
• Press M-s e to open the raw sexp editor
• Edit the complete data structure
• Save with C-c C-c or cancel with C-c C-k

Deleting

• Place cursor on annotated text
• Press M-s - to remove the annotation

Listing All Annotations

• Press M-s l to open a grep-mode buffer showing all annotations in the current file
• Enhanced display: Shows thread status, priority, comment counts, and author info
• Click on line numbers, press Enter or n/p keys to jump directly to annotations
• Perfect for getting an overview of all your notes and their status

Cross-file Overview

• Press M-s 0 to browse annotations across all files
• Select a file from the completion list
• Statistics: Shows annotation counts and status summaries per file
• View all annotations for that file in grep-mode format
• Source file is presented along with grep-mode list of annotations

Org-mode Integration

Export your annotation threads to org-mode files for further processing:

• Press M-s o to export current buffer annotations to an org file
• Each thread becomes a TODO item with proper metadata
• Replies become sub-entries
• Status, priority, tags, and timestamps are preserved

Tips and Tricks

Workflow Suggestions

Enable the mode globally if you wish for all files!

(use-package simply-annotate
  :hook
  (find-file-hook . simply-annotate-mode)
  :bind
  ("C-c A" . simply-annotate-mode)
  ("C-c 0" . simply-annotate-show-all))

Smart Action Usage Patterns

• Quick annotation: No selection, M-s j to annotate current line
• Edit existing: C-u M-s j on annotated text to force edit mode
• Toggle view: M-s j on annotated text to show/hide annotation buffer
• Region annotation: Select text, M-s j to create detailed annotation

Advanced Editing Tips

• Bulk operations: Use M-s e to edit multiple comments at once in sexp mode
• Data migration: Copy annotation structures between files using sexp editing
• Precision control: Manually adjust timestamps, IDs, or metadata via sexp editing
• Complex threading: Create sophisticated reply structures that aren’t possible through the UI

Display Style Tips

• Use fringe mode for code files to minimize visual distraction
• Use highlight mode for documents where you want emphasis
• Use both mode for critical files requiring maximum attention
• Change styles on-the-fly with M-s ] based on current task

Performance Notes

• Annotations are loaded on-demand per buffer
• Large numbers of annotations (100+) may slightly impact performance
• Fringe mode generally has better performance than highlight mode
• Threading: Complex threads (10+ replies) may slow annotation buffer rendering
• Sexp editing: Large annotation structures may take a moment to format and parse