Das @docmd/plugin-threads-Plugin ermöglicht kollaboratives Inline-Kommentieren und Textannotationen auf allen Dokumentationsseiten. Hervorhebungen und Diskussionsthreads werden nativ in Markdown-Quelldateien mithilfe benutzerdefinierter Container-Blöcke (::: threads) gespeichert. Es ist keine externe Datenbank erforderlich.

Ursprünglicher Autor: @svallory

Installation & Setup

Installieren Sie das Plugin über die CLI:

npx @docmd/core add threads

Aktivieren Sie die Thread-Konfiguration in docmd.config.json:

Live-Entwicklungs-Server-Anforderung

Die interaktive Kommentaroberfläche, Texthervorhebungs-Werkzeuge und Markdown-Persistenzaktionen erfordern einen aktiven lokalen Entwicklungs-Server (docmd dev) mit einer funktionierenden WebSocket-RPC-Verbindung.

Da Threads requiresLiveServer: true deklariert:

• Entwicklung (docmd dev): Der Ausklapp-Tab, die Inline-Vorschaukarten, das Auswahl-Popover und die Thread-Seitenleiste sind vollständig geladen und funktionsfähig.
• Statische Produktions-Builds (docmd build): Client-Skripte und CSS werden automatisch weggelassen, damit öffentliche Websites ultraschnell, schlank und frei von inaktiven UI-Elementen oder fehlerhaften WebSocket-Verbindungsversuchen bleiben. Vorhandene Markdown-Syntax (::: threads und ==Text=={t-...}) wird weiterhin fehlerfrei geparst.
• Manuelle Überschreibung: Wenn Sie die Threads-Client-Assets ausdrücklich auch in statische Builds bündeln möchten, konfigurieren Sie "devOnly": false unter plugins.threads.

Globales Konfigurationsbeispiel

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

Workflow-Übersicht

1. Textauswahl: Wählen Sie während der lokalen Live-Entwicklung (npx @docmd/core dev) Fließtext aus.
2. Kommentar-Popover: Geben Sie Feedback im Popover-Modal ein.
3. Anker-Injizierung: Ausgewählter Fließtext wird mit einer Thread-Kennung hervorgehoben (==hervorgehobener Text=={t-a1b2c3d4}).
4. Markdown-Persistenz: Thread-Strukturen werden am Ende der Markdown-Datei als ::: threads-Block angehängt.
5. Git-Synchronisation: Der Diskussionsverlauf wird in der Quellverwaltung zusammen mit Dokumentbearbeitungen gespeichert.

Interaktive Vorschau

Text mit angehängten Diskussionen erhält Inline-Farbhervorhebungen. Thread-Karten werden darunter gerendert:

Zusätzliche Hervorhebungen durchlaufen automatisch verschiedene Farbpaletten:

Gelöste Diskussionen werden im abgedunkelten Zustand angezeigt:

Ein rechts verankertes Registerkarten-Element 💬2 schmiegt sich an den rechten Bildschirmrand und zeigt die Anzahl ungelöster Threads an. Das Überfahren von markiertem Text öffnet direkt eine Inline-Vorschaukarte im Dokumentinhalt, während ein Klick auf die Registerkarte die Seitenleiste öffnet. Threads bleiben beim Öffnen und Schließen der Leiste nahtlos erhalten, ohne die Seite neu zu laden.

Markdown-Speicherformat

Threads werden in Dokumentquelldateien mithilfe von Containerblock-Syntax gespeichert:

# Engine-Übersicht

Kernarchitekturfunktionen ==hervorgehobener Text=={t-a1b2c3d4} mit angehängtem Thread.

::: threads
  ::: thread t-a1b2c3d4
    ::: comment c-e5f6a7b8 "Alice" "2026-04-09"
      Dieser Text erfordert zusätzliche technische Details.
    :::
    ::: comment c-d9e0f1a2 "Bob" "2026-04-09" reply-to c-e5f6a7b8
      Mit zusätzlichen Spezifikationen aktualisiert.

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

Hauptfunktionen

• Textauswahl: Heben Sie beliebigen Fließtext hervor, um neue Threads zu verankern.
• Thread-Antworten: Verschachtelte Konversationsthreads.
• Emoji-Reaktionen: Fügt Kommentaren Zähler für Reaktionen hinzu.
• Auflösungsstatus: Markiert Threads mit Autorenattributierung als gelöst.
• Autorenidentität: Lokale Git-Anmeldeinformationen lösen Avatar- und Profildetails automatisch auf.

RPC-Aktionen-API

Das Threads-Plugin stellt WebSocket-RPC-Endpunkte bereit, die über docmd.call() zugänglich sind:

Speicher für Autorenprofile

Autorenprofile werden in <docsRoot>/.threads/authors.json zwischengespeichert:

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