imark

[!NOTE] Imark opens reading, and reading is what it is for. The switch in the toolbar turns it into an editor for the file you already have open — see Editing — and comments go into the document itself, as HTML comments, so they travel with it.

What it does

• Editing, when you ask for it — one switch in the toolbar, and the page becomes the file: line numbers, Markdown in colour, a bar beside every line you have changed, ⌘S to write it. Reading is the state it opens in
• Comments in the file — select, comment, edit or delete, and the note lives in the document as an HTML comment, so it survives being emailed, committed, or opened in anything else. ⌘Z undoes any of it
• Quick Look previews — the space bar in the Finder renders the document, not raw text, using the same engine as the app
• Live reload — saving in your editor updates the view in under 300ms, keeping your scroll position, and it survives the delete-and-rename that editors call an atomic save
• Foldable outline — headings in the sidebar, with sections you can collapse; past twenty entries it opens folded, so a changelog is one row per version
• Outline rail — a tick per heading down the edge of every document, tapering around the pointer, with a card that names the section before you commit to going there
• Wiki-links — [[note]] resolves against the folder and opens in the same window, with back and forward history
• The folder and the recents — every .md beside the open document, plus the last five you opened from anywhere else
• Everything GitHub-flavoured — tables, task lists, footnotes, front matter as a header card you can put away from the View menu, syntax highlighting, Mermaid diagrams, KaTeX maths
• Actions on a selection — comment on it, translate it on device, or search the web for it in your default browser
• Find with a counter — ⌘F highlights every hit and tells you which one you are on
• Tabs — several documents in one window, with everything macOS gives a tabbed app: ⌘⇧[ and ⌘⇧], drag a tab out, Merge All Windows
• Offline where it counts — documents render with every request blocked by a content security policy, KaTeX fonts embedded, remote images refused on purpose

Screenshots

Document window	Quick Look preview

Both are rendering testdata/showcase.md. For the full sweep — every construction, every kind of comment, and enough headings that the outline folds itself — open testdata/everything.md.

Install

brew install --cask migsilva89/imark/imark

Or download the latest release and drag Imark.app into /Applications. The disk image is signed and notarised, so it opens without a Gatekeeper warning.

macOS 14 or later. Imark checks once a day when you leave the option on in Settings. When a new version exists, click Install and Relaunch — the app downloads it, verifies both signatures, replaces itself and opens again.

To make it the default for .md: launch it with no document open and click Make Imark the default for .md, or use the same item in the Imark menu. Once it is the default, both quietly disappear.

From a terminal

Imark ▸ Install the imark Command… links imark into /usr/local/bin, or into ~/.local/bin when that first one belongs to root — the alert says which, before it writes anything.

imark notes.md            # opens it in the copy already running
imark notes notes.md      # the notes somebody left in it, as text

A document already open comes forward instead of opening twice. This is separate from making Imark the default for .md on purpose: open notes.md should still go to your editor.

Editing

The toolbar has one switch: an eye and a pencil. The eye is the app you know — nothing on screen offers to change the file. The pencil replaces the page with the document as text, in a plain editor: line numbers, Markdown in colour, a bar in the gutter beside every line that differs from the file on disk, and the system's own find bar with its counter and its replace field.

⌘S writes it. Until you do, live reload stands still — following the file is the reason this app exists and also the one thing that could erase what you typed, so while there is anything unsaved the window stops watching. The close button carries the system's edited dot, Revert throws the buffer away and reads the file again, and closing the window or opening another document asks first.

A save cannot land on somebody else's work: it goes through the same check every comment does, and if the file moved since Imark read it the save is refused and says so. ⌘Z afterwards puts the document back the way it was.

Open in… stays in the toolbar while you edit, with Cursor, VS Code, Zed, Sublime — and Claude and ChatGPT — so the moment a change is bigger than a line, the file goes to something built for it. Imark runs nothing on your machine and asks nothing of your accounts; when you come back, the reader is where you left it, and the notes are still in the file.

Comments

Select a phrase, press the speech bubble, write, press ↵. The quoted words get underlined, a dot appears in the margin, and clicking either opens the note. Pick one of five colours while writing it, or change it later. The card carries Edit and Delete, and ⌘Z undoes any of it — writing, editing or deleting.

Without a selection there is a + in the margin, level with whatever the pointer is beside. On a list or a table it offers the item or the cell you are level with rather than the whole block — an agent's twenty-item list is twenty things to disagree with, not one — and the note quotes that item, so the file says which one it meant to anyone who reads it without the app.

The note is stored inside the .md file, as an HTML comment:

Rows move in batches of 500, and the deadline is generous but achievable.

<!-- imark quote="generous but achievable" by="john" at="2026-08-02T14:31Z"
Achievable with which team? This needs a number, not an adjective.
-->

Which means it travels with the document instead of living in a database only this app can read:

The quote= is what makes the note legible in raw text: someone opening the file in Vim can see what it refers to without counting lines. If the quoted words are later edited away the note goes orphan — still visible, still attached to its block, marked as having lost its anchor. There is no fuzzy matching, because a note in the wrong place is worse than a note without an exact one.

Four ways to get at them, because they answer different questions. The count in the status bar opens the list — every note at once, out of the document. ⌘⇧C opens them all in place, each under its own block. ⌘' and ⌘⇧' step through one at a time. And a rail down the left edge marks where they are, so three clustered in one section is visible at a glance.

File › Export Comments as Text… writes a copy — not the document — with every note turned into a blockquote, for the review the other person has to read on GitHub:

Rows move in batches of 500, and the deadline is generous but achievable.