Comments

[monsieurhannes]

This post summarizes the current state of the discussion in this ticket and the plans to implement (original report at the bottom):

Open tasks

• [ ] @max-nextcloud will align with @nimishavijay on open design questions
• [ ] @max-nextcloud is looking into implementing html comment support as a technical baseline

Summary

Initial sketch with available comments indicated in text and a button to create a new comment on the current active section.

Allow comments on block elements (paragraphs, headings, quotes, ...):

• Allow create comments.
• Display existing comments.
• Allow removing ones own comments.

Motivation

Comments are useful in many situation. They allow adding information that directly relates to parts of the document without adding it directly to the document content.

Comments can be particularly helpful when drafting documents and during a review process.

Comments on block elements attach the comment to the relevant section on the document while avoiding the complexity of in line comments such as overlapping comment ranges.

Specification

Comments can be added to all block elements:

• Paragraphs
• Headings
• Quotes
• Callouts
• Code blocks
• Images
• Link Previews
• Tables
• all types of Lists

Alternatives

Inline comments

This draft mainly came out of the discussion of in line comments in #185. In line comments allow commenting on a precise range of text, which is hard to represent in markdown.

Footnotes

While footnotes could also be used to represent comments, they serve a different purpose.

2142 discusses footnotes.

User Interface Elements

• Button to add a comment to a block element
• Indicator that there are comments on an element
• List of comments on an element
• Button to remove ones own comment

Implementation

• Comments will be serialized in markdown.
• They will be implemented using the standard way in text:
  • Markdown-it extension parses them to html.
  • Tiptap nodes represent them in the editor.
  • toMarkdown function to serialize them.
• Comments can contain multiple block nodes themselves.

Out of scope for now (but maybe future)

• Edit my own comments.
• Reply to other comments.
• Suggest changes.
• Integrate with nextcloud comments system.
• Integrate with document chat (talk).
• Notify about comments.
  Initial report

Is your feature request related to a problem? Please describe. No, but it would be great to have the ability to comment text directly in the line.

Describe the solution you'd like Similar to gdocs and word, marking a text and writing a comment on the side.

Describe alternatives you've considered Linking a specific part of the text in the comment section in the panel on the right could also be a solution, maybe for the start, being able to link headlines #H2

Just an idea, might be too ambitious, but maybe sth. for the backlogs.

[jancborchardt]

@monsieurhannes yes, this would be very useful. Could you show screenshots from how Google Docs, Word and others do it as examples?

[juliusknorr]

Besides the frontend we of course need to think of a proper way how we represent the comments in markdown.

[tiotrom]

This would be such an awesome thing

[juliusknorr]

Please use the Github Reactions feature instead of commenting that also need a specific feature. That way we can see your support without notifying all users subscribed to a given issue.

[joshp23]

Markdown footnotes would be a possibility to represent in MD

[jtoloe]

HackMD has this functionality. See https://hackmd.io/s/how-to-use-comments for examples. I do not think that the comments are stored in the markdown file.

[juliusknorr]

The issue with not storing it in the markdown file would be that we then loose the comments as soon as someone changes the file from outside (e.g. with a editor synced by the desktop client)

[juliusknorr]

Footnotes would be a possible way, but they limit comments to one cursor position in the text rather than having the possibility to mark a range of text and comment on that.

[jnnkB]

Maybe Critic Markup would be an option: http://criticmarkup.com/users-guide.php

[monsieurhannes]

Any development on this front? It seems like it gets mentioned more often recently. I guess Text is in a bit of competition with the big office suites which provide that feature already and maybe it's an overkill for Text. But at the same time Text is much more lightweight and accessible on all platforms. I'd be happy to help in any way - more in the UI than the programming part. 😆

[juliusknorr]

This would still be a nice to have feature, but is currently blocked by a proper approach to persist comments in markdown files, without impacting readability too much.

The only feasible option seems to be to use footnotes for this, but then you could only comment on cursor positions and not comment on a selected area.

[susnux]

I think range based comments are only possible with custom syntax. I would not use footnotes for this, as they might be added as a stand-alone feature in the future.

When talking about inline comments, how about HTML comment blocks? They are allowed as per markdown spec.

# Header
some text <!-- some comment --> text

But when talking about range comments, then I could not even find one already used syntax for that. So to stick with current style of markdown syntax this could be one option:

# Header
?[some text](with comment)

[badrihippo]

Comments as per CriticMarkup

Since many people have been mentioning CriticMarkup in this and duplicate threads, here's how it looks in practice.

Comment (sticks to a specific point in the text {>> like this <<}):

Lorem ipsum dolor sit amet.{>>This is a comment<<}

Highlight (highlights {==a specific passage==}{>>like this<<}):

Lorem ipsum dolor sit amet, consectetur adipiscing elit. {==Vestibulum at
orci magna. Phasellus augue justo, sodales eu pulvinar ac, vulputate eget
nulla.==}{>>confusing<<} Mauris massa sem, tempor sed cursus et, semper
tincidunt lacus.

To me this looks like an elegant solution, which will preserve the comments even when edited with an external editor.

One caveat is that the CriticMarkup parser doesn't currently support broken markdown tags: a highlight has to include both the opening and closing of the tag to work properly. They hope to fix this in the future and allow partial tags to be highlighted too.

First steps

I think even the first option (just inline comments at a specific point in the text, not necessarily tied to a specific highlighted passed) will be a great help for collaborative editing. Given that it also looks easier to implement, how about we start with that, and put highlights as a feature later down the line if needed?

Linking to the user

What remains to be standardised is how to link the comment to a NextCloud account. The simplest way is to prepend the commenter's name before adding the actual comment, like this:

NextCloud has a great collaborative editor {>>>badrihippo@domain.tld: and now we have comments!<<<}

If we're only saving these comments directly to the Markdown file, there is obviously no way to verify the identity: anyone can type my username into the text file to make it appear as if I wrote the comment. To prevent this, perhaps we could implement this in multiple stages:

1. Start with identity-less comments: have them simply show up as speech bubbles without specifying who wrote the comment.
2. Start specifying the comment author with the above syntax, but also save the comment information externally so that it can be cross-checked. If the comment doesn't match, we could either remove it (destructive) or display a warning saying that the identity of the commenter could not be verified. (I prefer the second option)
3. (Not sure how feasible this is) scan the Markdown file everytime it is edited, so that if the user has manually inserted a comment with the given syntax, and under their username, then it gets added to the database as "their" comment. This goes hand-in-hand with the "could not be verified" comment handling behaviour

---

That's as far as I've thought so far—is there anything I missed, any concerns, or anything that could be done better? (Tagging @juliushaertl for what you think of the markdown mechanics, and if you have any concerns about using CriticMarkup instead of vanilla markdown or whatever we use right now).

[mejo-]

Thanks a lot @badrihippo for the thorough reply. I like your approach. CriticMarkup doesn't look very active, but the syntax seems sensible nevertheless.

And there is a markdown-it plugin for CriticMarkup (that is very old but then it's only a few lines of code anyway). We would need that for serializing the markdown into HTML.

There's also vimtaai/critic-markup which might help as code inspiration (e.g. for parsing regexes).

[pierreozoux]

This discussion looks a lot like this one: https://github.com/hedgedoc/hedgedoc/issues/2879

I would love that nextcloud/text and hedgedoc agree on the same solution so that I could use hedgedoc and other people text, and this would be compatible :)

It is probably utopia, but this is the way I feel, a common internal standard to collaborate between different tools, and different UI according to preferences.

Sorry to open the scope of the discussion, don't hesitate to label it as offtopic.

Have a nice day!

[codedust]

To get a better feeling for this solution, here are some screenshots of popular text editors, as @jancborchardt suggested:

Google Docs

LibreOffice Text

HackMD

see https://hackmd.io/s/how-to-use-comments

OnlyOffice

[max-nextcloud]

I played with some plain commonmark markdown syntax. Actually it's quite difficult to come up with something that will work if multiple comments exist for overlapping ranges.

Using links with titles would be nice in terms of the rendering outside text - but it does not allow editing in other editors that do not allow editing the underlying markdown directly. Otoh I wonder which editors this would be.

## Try CommonMark

[You💬][1][ can 💬][2][ try💬][1] CommonMark here.  This dingus is powered by
[commonmark.js](https://github.com/commonmark/commonmark.js), the
JavaScript reference implementation.

[1]:  "Comments"

* @ali: My comment to this...
* @bob: I'd rather...

[2]: mention://cem "Comments:
@cem: actually you can't...
"

[mejo-]

@max-nextcloud and me discussed this briefly:

• Inline comments should be persisted in markdown (not in DB or yjs document) to
  • make them accessible in markdown readers
  • prevent sync issues when the document source got edited
• Inline comments will most likely mostly be used in the web interface.
  • Focus is to not break legibility of the markdown source. Therefore we tend to persist the comments at the end of the document, like footnotes.
• If we support comments for ranges of comments, we probably should not support nested or overlapping comments for the sake of simplicity. We have to ensure proper error handling in case of broken/nested/overlapping comments syntax in the markdown though.
• Syntax idea is to use link references with a link title that start with 💬
• UI:
  • Use a bubble like the link bubble to display and edit comments
  • Allow to add comments via menu bar and keyboard shortcut
  • Visualize existing comments with highlighting/underlining the commented range. When putting cursor inside the comment, the comment/link bubble will open

[max-nextcloud]

I've been pondering this some more. Haven't really made up my mind yet - so throwing some random thoughts out.

Using links to denote comments

We could use links to anchors in the file to denote comments like mentioned above.

[Text I want to comment on](#comment1)
... more text...
... end of the actual content

----
# Comments

<div id="comment1">

> Text I want to comment on

@max-nextcloud : my comment
@someone-else: their comment
</div>

Pros:

• This could enable a meaningful rendering in other markdown tools.
• Uses standard markdown syntax + some minimal html - which is also valid in markdown.
• Would allow replying to comments as each comment has it's own section.

Cons:

• Comments are separated from what they comment on.
• We might be left with dangling comments after the original content has been removed.
• We might be left with links pointing nowhere if the comment in question has been removed
• Cannot comment on links or text that contains links, comments cannot overlap.
• What markup is valid in comments? Whole can of worms there.

CriticMarkup

Pros:

• Documented standard.
• Allows comments on links.
• Comments are inside the paragraph they refer to.
• Clearly limits content of comments to inline content.

Cons:

• Is any other tool actually using this? I saw discussions on hedgedoc, hackmd and cryptpad but none of them implemented it.
• If not parsed syntax can be somewhat confusing.
• Does not work well for replying to comments.

Using our existing comments on files system

We do have comments in Nextcloud. It's not used so often I think - but we could improve that by embedding it in text.

Pros:

• Easily stores metadata about comments (author, timestamp).
• Permissions already build in - i can edit or delete my own comments.
• Would work on any file type supported by text - not just markdown.
• Keeping the meta conversation separate from the file content.

Cons:

• No replies either.
• Would need extension to support referring to specific text.
• Would get out of sync if file content is updated outside of text.

[manicmarvin]

My two pence [disclaimer: not really contributing code to this repo].

Using links to denote comments

Cons:

• Comments are separated from what they comment on.
• We might be left with dangling comments after the original content has been removed.
• We might be left with links pointing nowhere if the comment in question has been removed

Apart from the other cons, IMO these issues pose serious obstacles for large groups where not everyone is familiar with the comment protocol. Those editing files primarily in an external editor are almost sure to break others comments because it will be easy to miss that the comment even exists or how it works.

CriticMarkup

Pros:

• Comments are inside the paragraph they refer to.
• Clearly limits content of comments to inline content.

These address the issue I mentioned above, it's harder to miss new unique syntax and will probably ensure unfamiliar users pause and consider before making changes.

Cons:

• Is any other tool actually using this? I saw discussions on hedgedoc, hackmd and cryptpad but none of them implemented it.

even if no one else chose this path, it seems to me to be the best path for NC, given how the files within it are edited by a different people using a plethora of different editors.

* If not parsed syntax can be somewhat confusing.

A pro, not a con, IMO.

Using our existing comments on files system

Cons:

• Would need extension to support referring to specific text.
• Would get out of sync if file content is updated outside of text.

These two issues make this path non-viable, IMO. I am constantly thinking of the way nextcloud is often used -- in large heterogenous groups or organisations where not everyone is familiar with all features of all tools.

[juliusknorr]

From the discussion with @marcoambrosini and @max-nextcloud:

We currently see 3 options

• footnotes to comment on positions

• footnoites comment on paragraph (ending)

• comment on ranges which would not be possible in markdown

• we could aim for more features if we'd introduce a new file format, but not markdown compatible, likely not an option

• likely preferrable to have comments on paragraphs (like on github diffs)

• suggestions could be like on github

Stretch goals

• would be interesting to merge with existing comments app (maybe as a stretch goal)
  • still preferred to have the comments in the markdown file, otherwise duplicate places to hold data
• replies (stretch goal)
• suggest changes
• approve reject

[susnux]

• footnotes to comment on positions

I would rather go with HTML comments as a syntax that way we would also solve the problem that text does not preserve HTML comments

[juliusknorr]

The benefit of footnotes would be that it does not impact readability of the plain markdown too much, with html comments that is probably getting quite messy if there are a couple of comments on the same line

[marcoambrosini]

@juliushaertl could we schedule a kickoff meeting with stakeholders to scope down this feature?

[susnux]

The benefit of footnotes would be that it does not impact readability of the plain markdown too much, with html comments that is probably getting quite messy if there are a couple of comments on the same line

Thats true, I was just hoping that text would now preserve my comments 😄

[max-nextcloud]

I started #6478 to discuss the approach we're currently pushing forward: Comments - but not in line but rather on a per block element basis.

[juliusknorr]

@max-nextcloud Let me close this in favor of https://github.com/nextcloud/text/issues/6478 then. Don't see a point in keeping two issues open if we're aiming for one implementation of comments ;)

[juliusknorr]

Or wait, since this probably has more detailed description. Let's use this one. I'll copy the current state of discussion over.

[juliusknorr]

Copying over design spec draft from @nimishavijay (https://github.com/nextcloud/text/issues/6478#issuecomment-2385154856)

---

References

Google docs


Notion


Confluence


Design specs

Existing comments

• [ ] Highlight the text (not the block, that looks too, well... blocky 😀) in color-primary-element-light at 0.5 opacity
  • [ ] Nice-to-have: a border-bottom: 2px solid var(--color-primary-element) also with 0.5 opacity
• [ ] On hover: highlight opacity: 1
• [ ] On click: highlight opacity: 1 and the comment opens

• [ ] Comment box: max-width: 300px
• [ ] Show avatar (34px), name, and comment with actions in a 3dot menu
  • [ ] nice-to-have: timestamp
• [ ] Actions in the 3 dot menu: Delete if it's user's comment
  • [ ] nice-to-have: "Mark as resolved" if it is not user's comment

New comments

• [ ] When the cursor is in a block or when you hover on a block, a comment button should appear (TBD: where and how it looks)
• [ ] When you click on comment button:
  • [ ] text in block gets highlight (opacity 1)
  • [ ] New comment element opens

New comment element:

• [ ] Show user's avatar (24px), name, input field, comment and cancel buttons
• [ ] When you click on comment, the comment gets added and is shown as normal

Mobile view

Mockups TBD

• [ ] Don't show the comment icon next to the block, instead show it on the top bar
• [ ] Existing comments are stickied to right below the block they are associated to
• [ ] Same for new comments, plus the keyboard opens

TBD:

• [ ] Placement and exact of the comment button next to the block (left side? right side? secondary button? shadow?)
• [ ] Placement of comment action in the top bar
• [ ] Should there be a "Show/hide comments" toggle in the top bar?
• [ ] Interaction of comments and author colors
• [ ] How to show comments from different people:
  • do we need it for the MVP?
  • different colored highlight?
  • comment indication with avatar?

What do you think? :)