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:

Live Development Server Requirement

The Threads commenting interface, highlighting tools, and Markdown persistence actions require an active live development server (docmd dev) with an active WebSocket RPC connection.

Because Threads declares requiresLiveServer: true:

• Development (docmd dev): The slide-out handle, inline preview cards, selection popovers, and thread sidebar are fully loaded and operational.
• Static Production Builds (docmd build): Client scripts and CSS are automatically omitted to ensure that public production sites remain ultra-fast, zero-overhead, and free of broken WebSocket attempts or inactive UI widgets. Any existing Markdown threads syntax (::: threads and ==text=={t-...}) continues to parse cleanly without warnings.
• Manual Override: If you explicitly wish to bundle Threads client assets into static builds, configure "devOnly": false in plugins.threads.

Global Configuration Example

{
  "plugins": {
    "threads": {
      "sidebar": true,
      "devOnly": 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 Synchronisation: Discussion history is saved in source control alongside document edits.

Interactive Preview

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

Additional highlights cycle through distinct colour palettes automatically:

Resolved discussions display in a dimmed state:

A right-docked tab trigger 💬2 hugs the right edge of the viewport, displaying unresolved thread counts. Hovering over any highlighted text reveals an inline comment preview card directly within the content, while clicking the tab opens the discussion drawer. Threads persist seamlessly across drawer open and close states without reloading the page.

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/..."
  }
}