[Feature/Plugin] Specification for Commenting Feature

[zeigerpuppy]

Introduction

This is a proposed feature to permit annotation of documents with comments.

The primary aims of the commenting feature are to:

1. allow selecting a cursor position or selection in document and attaching comment
2. showing a side-panel with comment threads
3. responding to comments
4. marking comments resolved
5. (optional) allowing comments to propose changes in text - amend/delete/highlight

Various approaches were considered and previous discussed in hedgedoc/hedgedoc#657. The main technical question is whether to include the commenting within the markdown source document or to store the comments in a database. This specification chooses the database storage option because it enables commenting threads without polluting the source document with too much inline syntax.

Plan

• In the first instance, this feature will be developed as a plugin for RefMD v1
• Once RefMD v2 API is stabilised, it can be integrated as a core feature

Implementation

For each document (defined by document id):

• Corresponding THREAD entities can be created.
• Each THREAD is anchored to the document by an HTML comment, e.g. <!--CTHREAD:yTs5gh39dyagJKG-->.
• When a document is loaded, the database is queried for matching THREAD ids and the threads are populated in the commenting panel
• Each THREAD can have multiple COMMENTS
• Each COMMENT includes metadata about Creator and Datetime which is used to identify comment details
• Users can mark a comment or thread with TAGS, including a "resolved" tag

The current plan is to implement just commenting of document parts, but the functionality could be extended with attributes to mark suggested edits to the selected text. For instance, a comment metadata could mark the text for deletion or amendment. This feature would require extension of the UI with a "proposed changes" mode.

UI considerations

A similar implementation as shown in the mockup in hedgedoc/hedgedoc#657 (comment) would be a reasonable start.

The main proposed differences from that mockup are:

1. replace "delete thread" with "resolve thread" as it would be good to tag these threads resolved and filter them
2. include tagging functionality for threads and comments
3. include a filter and search comments bar at the top of the comment pane - search text of comments
   • filter by author or tag
   • show/hide resolved threads
4. (Optional) include a toggle for "proposed changes" mode in which proposed editing changes are saved and shown on the document

Specification

erDiagram
    %% Main entity for the comment thread
    THREAD {
        UUID TID PK "Unique Thread ID"
        UUID DOC_ID FK "RefMD document ID"
        string Commit_ID FK "Last commit of doc"
        string Anchor_start "Start anchor (line, pos)"
        string Anchor_end "End anchor (line, pos)"
        boolean Anchored "Is anchor still present?"
        datetime Created
        datetime Updated
        UUID Creator FK
        boolean Resolved
        datetime T_resolved "Time resolved"
        UUID W_resolved FK "Who resolved?"
    }

    %% Entity for tags
    TAG {
        string name PK
        string color
        string description
    }

    %% Entity for individual comments within a thread
    COMMENT {
        UUID CID PK
        UUID Creator FK
        datetime Datetime
        boolean Resolved
        datetime T_resolved
        UUID W_resolved FK
        string Content
    }

    %% Relationships
    THREAD ||--|{ COMMENT : "contains"
    THREAD ||--|{ TAG : "categorized by"
    COMMENT ||--|{ TAG : "tagged with"

Loading

[MuNeNiCK]

Thanks for writing this up.

I think an MVP is possible as a v1 plugin, especially for storing threads/comments in plugin records and keeping document-scoped state in plugin KV. A plugin can also mount its own editor surface and update the document content, so inserting anchors like <!--CTHREAD:...--> is possible in a plugin-owned view.

That said, for the UX described here, the current v1 plugin API is probably missing a few host/editor integration points:

• read the current editor cursor/selection
• replace or annotate the current selection when creating a thread
• add Monaco decorations/highlights for comment anchors
• scroll/select an anchor from a thread in the comment panel
• register a persistent document side panel, rather than only mounting a plugin-owned editor surface
• subscribe to selection/content changes in a stable host API

Without those, the plugin can still work, but it would likely need to provide its own editor/comment view instead of integrating cleanly into the standard document editor.

If this is useful, I can add the missing host APIs to v1 so a comments plugin can be implemented without making it a core feature yet.

[zeigerpuppy]

Thanks for looking over the specification, @MuNeNiCK

It would be wonderful to add in the missing host API features in v1 to allow integration of the plugin. In the meantime we can start work on the plugin.

[MuNeNiCK]

I have developed the comment plugin as shown below.
https://github.com/refmdio/comments-plugin

Please feel free to test it, and I will be happy to make any necessary corrections if you encounter any issues.