Inkling Markup

Inkling is a CriticMarkup editor for Obsidian. It is designed both for collaborative editing (with tools like Relay) and for reviewing your notes, providing a suggestion mode for tracking changes, comments anchored to text selections, and a comment-only mode for reviewers.

This is a fork of Commentator. Commentator was built by @Fevol upon the excellent work and advice of @kometenstaub (original plugin and parser). All credit for the plugin's foundation belongs to them.

Installing (via BRAT)

1. Install the BRAT community plugin
2. In BRAT: Add beta plugin → AndrewBroz/obsidian-inkling
3. Enable Inkling Markup in Settings → Community plugins

Upgrading from 0.11.x or older (plugin id inkling)

From 0.12.0 the plugin id is inkling-markup. The old id inkling now belongs to an unrelated plugin in the community store, so Obsidian offers that plugin's releases as an "update" to old installs. Do not click Update on an Inkling 0.11.x install (or "Update all"): it replaces Inkling with a different plugin.

1. In BRAT, check for updates (or re-add AndrewBroz/obsidian-inkling); this installs inkling-markup alongside the old copy
2. Enable Inkling Markup in Settings → Community plugins. On first load it imports your settings and hotkeys from the old copy and disables it
3. Click Uninstall old copy in the notice that appears (or uninstall the 0.11.x Inkling manually)

[!WARNING] This fork is in beta. It carries an extensive automated regression suite (1,100+ tests, including round-trip safety tests for accept/reject), but has not yet finished manual validation in live vaults. Use it in a test vault or a synced/backed-up vault first.

What's different in this fork

Data-safety fixes:

• Rejecting all suggestions no longer resurrects text from retracted additions
• "Accept/reject selected" no longer misfires at the start of a document (previously accepted everything)
• Substitution ranges are no longer corrupted (separator/metadata destruction) by the markup auto-correcter
• Vault-wide accept/reject refuses to apply stale positions to files that changed after indexing

Collaboration features:

• Comments anchored to selections — Select text > Add comment > {==highlight==}{>>comment<<} thread.
• Comment mode — A reviewer-friendly mode where text edits are blocked (with feedback) but commenting works
• Frontmatter-enforced modes — A note can force suggest/comment/off for everyone except listed authors (see Frontmatter)
• No unprotected mode — Every editing mode guards the CriticMarkup syntax (see Editing modes)
• Attribution on by default — New installs stamp author + timestamp metadata and prompt once for your display name. The vault-wide Suggestion View can filter by author and recency.

Maintenance: Modernized toolchain (ESLint 10 with Svelte linting, dprint, vendored dependencies), repaired release CI, and a large regression-test suite.

Editing modes

The editor toggle (status bar / note header) cycles through three modes:

Upstream Commentator also had a "Regular" mode that installed no protection at all, so ordinary typing could corrupt a note's markup (backspacing {++ into {+, deleting half of a range). It has been removed. Its one interesting property, seeing the raw brackets and metadata of the range under the cursor, is now the Reveal CriticMarkup syntax under the cursor setting (Editor settings), which works in every mode.

Frontmatter

Enforce an editing mode for a note via frontmatter that overrides the per-editor toggle:

---
inkling: suggest   # or: comment, off
inkling-authors: [Alice]   # optional: these authors are exempt from enforcement
---

off enforces plain Editing mode (nothing beyond the usual syntax protection): use it to override a reader's own default of suggesting or commenting.

The legacy commentator: / commentator-authors: keys still work (checked when no inkling key is present), so existing notes from before the rename don't need to be updated.

[!NOTE] This is not hard technical enforcement. Inkling is only appropriate for high-trust teams.

Developing

To set up a development environment:

1. Install the bun package manager from https://bun.sh/
2. Clone this repository (git clone https://github.com/AndrewBroz/obsidian-inkling.git)
3. Run bun install in the root of the repository
4. Run bun run build:dev to build the plugin
5. (Optional) For automatic plugin reload on each build, use bun run build:dev:hr (requires the Obsidian CLI)

Other commands: bun run test (jest suite), bun run lint (ESLint), bun run format (dprint).

Releases: bun run release-minor (or -patch/-major) bumps versions, commits, and tags; pushing the tag builds the GitHub release via CI (fallback: gh workflow run releases.yml --ref <tag>).

Roadmap

This project inherited a roadmap from Commentator and introduced its own priorities. No timeline is given. Items may be dropped for any reason.

Parser

• Parsing of CriticMarkup syntax (see CriticMarkup parser library)
• Parsing of annotations and extended syntax (see Syntax)
• Improving resilience to invalid markup

UIX

Commands

• Mark selection as Insertion/Deletion/...
• Accepting/Rejecting all changes in document
  • Via command palette (entire document/selection)
  • Via context menu (selection)
  • Via gutter markings (line)

Extensions

• Auto-close critic-markup brackets when typing
• Automatically correct invalid markup
• Automatically simplify dangling and (partially) empty markup

Suggestion View

• Vault-wide index of all suggestions and comments
  • Automatically create/re-synchronize on vault opening
  • Keep up-to-date with immediate changes in vault
• Custom view for viewing suggestions and comments over entire vault
  • Metadata rendering
  • Filter by recency
  • Filter by author (see also custom syntax)
  • Performance improvements
  • UIX/Scrolling improvements
  • Accept/Close selection of suggestions and comments

Editor

• Preview of Accept/Reject commands in editor
• Toggling suggestion mode on/off in editor
• Toggling comment mode on/off in editor
• Integration of toggles for suggestion mode, preview and comment mode with other community plugins
• Specify suggestion/comment-only mode in frontmatter (based on authorship)

Rendering

• Rendering of markup in Live Preview
• Rendering of markup in Reading View (Postprocessor)
• Rendering comments
  • In right-side gutter of document
  • On hover in document

Syntax

• Extend CriticMarkup syntax to allow for authorship and timestamp annotation
• Extend Comment markup to support comment threads
• Allow custom highlight colours for Highlight markup

Suggestion Mode

• Converting edit operations into appropriate markings
• Correct cursor placement through edit and cursor operations
  • Support different options for cursor movement (always stop when markup encountered, ...)
  • Full Vim Support (not planned in this fork)
• Toggle sequential CM state updating for improved multi-cursor support when inserting/deleting

Comment Mode

• Add comments to selection
• Smooth cursor movement through markup

API for other plugins

Other plugins can turn CriticMarkup into the note's original text: suggestions shown as rejected, comments removed, highlights unwrapped.

const api = app.plugins.getPlugin("inkling-markup")?.api;
if (api && api.version >= 1) {
    const original = api.toOriginalText(markdown);
}

version changes only on a breaking change. Transclusions of notes containing CriticMarkup are displayed using this original text.