The @docmd/plugin-threads plugin enables collaborative inline commenting and text annotation across documentation pages. Highlights and discussion threads are stored natively inside Markdown source files using custom container blocks (::: threads). No external database is required.

Original Author: @svallory

Installation & Setup

Install the plugin via CLI:

npx @docmd/core add threads

Enable thread configuration in docmd.config.json:

Global Configuration Example

{
  "plugins": {
    "threads": {
      "sidebar": true
    }
  }
}

Workflow Overview

1. Text Selection: Select prose during local live development (npx @docmd/core dev).
2. Comment Popover: Enter feedback in the popover modal.
3. Anchor Injection: Selected prose is highlighted with a thread identifier (==highlighted text=={t-a1b2c3d4}).
4. Markdown Persist: Thread structures append to the bottom of the Markdown file as a ::: threads block.
5. Git Synchronization: Discussion history is saved in source control alongside document edits.

Interactive Preview

Text with attached discussions receives inline color highlights. Thread cards render below:

Additional highlights cycle through distinct color palettes automatically:

Resolved discussions display in a dimmed state:

A floating discussion trigger 💬2 displays unresolved thread counts in the bottom corner.

Markdown Storage Format

Threads are saved inside document source files using container block syntax:

# Engine Overview

Core architecture features ==highlighted text=={t-a1b2c3d4} with an attached thread.

::: threads
  ::: thread t-a1b2c3d4
    ::: comment c-e5f6a7b8 "Alice" "2026-04-09"
      This text requires additional technical detail.
    :::
    ::: comment c-d9e0f1a2 "Bob" "2026-04-09" reply-to c-e5f6a7b8
      Updated with extra specifications.

      ::: reactions
        - 👍 Alice
      :::
    :::
  :::
:::

Core Features

• Text Selection: Highlight arbitrary prose to anchor new threads.
• Threaded Replies: Nested conversation threads.
• Emoji Reactions: Add reaction counters to comments.
• Resolution State: Mark threads as resolved with author attribution.
• Author Identity: Local Git credentials resolve avatar and profile details automatically.

RPC Actions API

The Threads plugin exposes WebSocket RPC endpoints accessible via docmd.call():

Author Profile Storage

Author profiles are cached in <docsRoot>/.threads/authors.json:

{
  "alice@example.com": {
    "name": "Alice",
    "avatarUrl": "https://gravatar.com/avatar/..."
  }
}