Margin Comments

by Jonathan Sanchez
5
4
3
2
1
Score: 52/100

Description

Comment on your notes like in Google Docs: reply in threads, resolve and review every thread in a side panel. Comments live in a hidden folder, never in your Markdown, and follow the text as you edit.

Reviews

No reviews yet.

Stats

3
stars
387
downloads
0
forks
43
days
3
days
5
days
228
total PRs
2
open PRs
15
closed PRs
211
merged PRs
211
total issues
0
open issues
211
closed issues
240
commits

Latest Version

5 days ago

Changelog

Added

  • Restore held comments to this note... lists the comments set aside for notes that went missing (old path, open threads, last update) and restores the chosen set to the active note. Nothing is removed until the note holds them (#432).

Fixed

  • A note edited between two moves made outside Obsidian keeps its comments: when it is the only candidate with the same file name, it gets them all, and the ones whose text changed show as orphaned threads instead of staying held (#431).
  • Comment highlights show inside rendered tables and callouts in live preview, and clicking them opens the thread (#419).
  • The comment gutter no longer appears inside a table cell being edited, nor shifts its text (#418).
  • The composer and popover open next to a selection inside a rendered table, not at the window's edge (#420).
  • "Add comment to selection" comments the words selected in a rendered callout instead of the whole line.
  • Inside ==highlight== only the underline is drawn, so the colours no longer blend into brown.
  • Quotes from table rows show their cells without the pipe syntax in the panel (#422).

README file from

Github

Why Margin Comments

  • Nothing in your notes. Comments live in a hidden folder, not in the Markdown and not in a file next to it, so your notes read and diff exactly as before.
  • Comments follow the text. Edit around a comment, rename the note or move its folder, and the comment stays on the words it was about. If they are gone, it is kept as an orphan rather than lost.
  • Real threads. Reply, resolve and reopen, and review every thread for one note or the whole vault.
  • Made for the phone too, with touch-sized controls and highlights in reading mode.

Use it to review drafts, collect an editor's feedback, keep reading notes, or discuss a vault shared through Git.

What it does

On your phone

Markers stay visible without hover, controls are sized for a thumb, and threads open in a sheet at the bottom of the screen. Colours come from your theme, light or dark.

With AI agents

Comments are plain JSON in a documented format, so an AI agent such as Claude Code, or any script, can read your open threads, reply to them and resolve them. Obsidian picks up the change while it is open. Your notes stay clean: nothing is written into the Markdown for the agent to find. The agent contract describes the files and how to write them safely.

Get started

  1. In Obsidian, open Settings → Community plugins → Browse and search for Margin Comments. Select Install, then Enable.
  2. Open a note, hover the left margin of a line and click the marker. To comment on a few words, select them first.
  3. Open the panel from the ribbon icon or the Toggle comments panel command to see every thread.
  1. Download main.js, manifest.json and styles.css from the latest release.
  2. Create the folder <your vault>/.obsidian/plugins/margin-comments/ and copy the three files into it.
  3. Reload Obsidian, then enable Margin Comments in Settings → Community plugins.

Open Settings → Margin Comments.

Setting Default What it does
Author name empty The name stamped on comments you write from now on.
Gutter icons on Shows the markers in the left margin. Without them, add comments with the Add comment to selection command.
Comment count on Badges a marker with the number of open threads on its line, when there is more than one.
Highlight commented lines on Tints lines that carry an open comment, in editing and reading mode.
Follow the theme accent on Takes the highlight color from your theme.
Highlight color none Appears when Follow the theme accent is off. The color used in every theme.
Fuzzy matching tolerance 0.3 How far edited text may drift before a comment stops finding it.
When a note is deleted Delete its comments Deleted comments are held on disk and come back whenever the note does, including after a restart or a rename made outside Obsidian. Kept comments stay readable in the all-notes view.
Side Right Which sidebar the panel opens in.
Sort order Document order Document order, date created, or last activity.

None has a default hotkey. Bind the ones you use in Settings → Hotkeys.

Command What it does
Add comment to selection Comments on the selected text, or on the line holding the cursor.
Toggle comments panel Opens or closes the panel.
Go to next comment Moves the cursor to the next commented line.
Go to previous comment Moves the cursor to the previous commented line.
Resolve all comments in this note Resolves every open thread in the note, after confirming.

Comments live as JSON files in a folder at the root of your vault: one file per commented note, plus an index. The folder is .margin-comments/ by default, which is hidden. You can choose a visible name under Storage folder in settings; Move comments copies the files there, merges them by comment id with anything already in the new folder, and removes the old folder once it is empty. Your Markdown files are never modified.

Each comment remembers the words it was made on and the text around them, not a line number. It follows those words as you edit, and moves with the note when you rename it or move its folder. A comment whose words are gone is kept and shown as orphaned.

A damaged comment file is set aside and reported, never overwritten.

Syncing. Git, iCloud and Dropbox sync the folder like any other. Obsidian Sync skips folders that start with a dot, so with the default folder your comments stay on the device where you wrote them.

Using Obsidian Sync? Set Storage folder to a visible folder on every device and turn on Sync all other types in Sync settings. Without it, comments may stay on the device where you wrote them. Enable it to be safe: whether the default Sync settings carry the folder is not verified. Use the same folder on every device, because the folder name is stored in each device's data.json, which may not sync. If two devices edit the same note's comments at once, the last save wins.

Large notes. The panel draws every thread it shows. A note with a thousand comments takes about a quarter of a second to draw, and scrolling stays smooth.

Each comment file is plain, unencrypted JSON. For every comment it stores the note's path, the commented words with about 50 characters on either side, the comment itself, the author name from settings, and timestamps.

Because the folder holds excerpts of your notes, treat it as part of your vault:

  • Publishing a vault with Git, Quartz or similar tools publishes the folder too, unless you exclude it. That can include excerpts from notes you did not publish.
  • Sharing a vault shares every comment and author name in it.
  • Deleting text from a note does not remove it from a comment until the comment is deleted.

To keep comments out of Git, add your storage folder (.margin-comments/ by default) to .gitignore.

Contributing

Bug reports and pull requests are welcome. See CONTRIBUTING.md for the development setup.

License

MIT