Feature Request: Comment and edits with CriticMarkup

[zeigerpuppy]

It would be great to have a simple editing system built into HedgeDoc. This would enable editors and reviewers to make non-destructive comments and edits to the markdown document.

This proposal could be implemented as such:

1. have an "editor/reviewer" mode which enables the following tools/buttons from the CriticMarkup syntax:
   • Addition {++ ++}
   • Deletion {-- --}
   • Substitution {~~ ~> ~~}
   • Comment {>> <<}
   • Highlight {== ==}{>> <<}
2. enable a sidebar which shows the location and summary of edits and allows commenting on edits
   • clicking on an edit takes the user to the location in the document
   • users of the document can add additional comments in the sidebar to discuss edits (also added to source document with CriticMarkup
   • each comment's author is tracked
3. enable an "Accept/Reject Change" button in the sidebar for each comment

[ccoenen]

I would like to point out that any addons onto MD should be very carefully thought through. We currently have a few syntax extensions, one of which is the Externals Syntax {%youtube %} and so on. These are - as far as I know - going to be replaced in the next release, but we really should consider if we want to add another set of things instead.

This is also loosely related to https://github.com/hackmdio/codimd/issues/917 where the same thing was brought up before we separated from HackMD.

[SISheogorath]

I also don't know if it makes sense to have comments etc. Within the document or if it would make more sense to keep them outside of it.

There is one thing I would really consider the important achievement of HedgeDoc 2.0 and that's the unification in syntax that @ccoenen already mentioned.

We shouldn't have any syntax in a document that Humans don't get or that cause bigger problems/confusions in other renderers.

That's why we removed the custom syntax and replaced it with simple hyperlinks.

You can already use quotes and sub-quotes to discuss and comment on things in HedgeDoc. Maybe we should either look into improving this in order to render it a bit more special or we should store the comments outside of the document and somehow use annotations. But honestly speaking I don't see this in 2.0, earliest in 2.1.

[zeigerpuppy]

I believe the advantage of having comments in the document is that it also keeps consistency with other markdown tools. A HedgeDoc document should ideally retain the ability to be exported as valid markdown as a single file. This makes it simpler to extend the document rendering in the future. I am particularly interested in using HedgeDoc as a collaborative editor for scientific documents. So, for example, it's easy to pull a HedgeDoc file and process it using R libraries to achieve a variety of outputs. This becomes a lot more difficult if the content is not available via the /download call.

I do agree with @SISheogorath, however, that rendering of CriticMarkup could become tricky to read if not handled properly.

That's why I think it'd be great to have a sidebar in an "review mode" that provides a sort of index of changes (and comments). Perhaps all of this CriticMarkup could be hidden in normal viewing or editing mode.

I think there's a bit more thought to be put into this with regards to UI and how the output format is affected, but the two modes seems to be one way of keeping the viewing experience simple.

[mrdrogdrog]

Our markdown dialect already differs so much from CommonMark and GFM that it's fair to name it HFM. (@DerMolly please link the doc pr that explains that). While we agreed not to overload our dialect I just must say that this feature seems to be very useful. Also it's not the first time someone requests a way to comment a document.

It should be pretty easy to implement the basic rendering, an overview to see all critics and accept/reject buttons.

But I'm not quite sure how to implement the "discuss edits" request because criticmakup doesn't provide a syntax for conversations.

[DerMolly]

A number of Comment {>> <<} and Highlight {== ==}{>> <<} one after the other?

[mrdrogdrog]

A number of Comment {>> <<} and Highlight {== ==}{>> <<} one after the other?

Well yes, you could do that, but that would blow up the document and decrease readability.

[sacha-sentier]

Hi there,

I would also like this feature.

But I'm a bit lost. It seems like we are discussing two distinct features here:

1. Being able to propose changes (without directly editing the document)
2. Being able to simply comment a selection of the document (maybe with a user interface similar to what we have HackMD)

In any case, it would be nice to be able to define specific permissions for that. Being able to comment without changing the content could be useful to publicly share a document, get feedback, but still make sure that all changes are going through a review process.

I'm not sure it's easy to implement this kind of feature with this kind of fine-grained permissions while still keeping all this info (comments and change proposals) in the original markdown document.

Maybe the changes feature could work a bit like Git? It doesn't change the document, but creates a patch that we can apply or reject. A bit like Pull Requests on GitHub.

[mrdrogdrog]

Hello @alexpirine, This issue is mostly about adding criticmarkup. What you describe here ("comments/suggestions without changing the document") is another feature request. Please open another feature request issue for that.

[jnnkB]

I quite like the idea of this issue. Would be so cool to have.

[nsheff]

@mrdrogdrog

This issue is mostly about adding criticmarkup. What you describe here ("comments/suggestions without changing the document") is another feature request. Please open another feature request issue for that.

There's another issue here regarding "comments/suggestions without changing the document": https://github.com/hedgedoc/hedgedoc/issues/657 -- but that issue was closed in favor of the current issue.

[lightnin]

This would be of great help to me in my workflow and I suspect to many other users.

[tomcxphillips]

Being able to make suggestions without changing the text would be really helpful for me, and for, i suspect, most people doing some form of collaborative editing

Perhaps one quick way to implement something like this would be to just add a dropdown arrow, then it would still stay in only 1 file. E.g.,

This way is only a marginal improvement though, the hackmd way might probably be best

[mrdrogdrog]

I'm not sure how to interpret this part:

Being able to make suggestions without changing the text

So here are my assumptions:

• "I want to add comments to the rendered document, but the markdown code should not change and the comment should not appear in the code": This won't happen. The core dev team had a talk and we decided that we're strictly against meta data that are not part of the markdown code. Not only would it be hard to keep this data in sync with the markdown, they would also be lost when you export the note. The markdown code is the single source of truth. If we implement comments/suggestions then we'll use extensions like CriticMarkup.

• "I want to mark a text in the rendering and click 'add a comment here'" . This could be possible because it's just an UI-Extension that could add/change the comment tags in the markdown source. But such a UI extension is out of scope for this issue because it's independent from the way hedgedoc stores comments.

Please stop commenting about "comment/suggestions" in general. If you want to discuss this, then open a discussion issue in https://github.com/hedgedoc/hedgedoc/issues . This one is a request for a specific feature.

[ptrxyz]

I would also love to have this feaure. Just to think about it during implementation, would this also be reflected in the permission model? Something like "Guests can only add/edit comments"?

[mrdrogdrog]

I would also love to have this feaure. Just to think about it during implementation, would this also be reflected in the permission model? Something like "Guests can only add/edit comments"?

This would be difficult because for using critic markup you need to change the content.