[Proposal] Extensions to the Critic Markup standard #50
Description
Hello, I am in the process of developing a CriticMarkup renderer and editor plugin for Obsidian, a Markdown notetaking tool -- the plugin itself can be found here.
During development, users have brought up that they would like to have support for collaborative workflows, by having notions of authorship, completedness, ..., and comment replies using the CriticMarkup syntax.
This, however, is not possible with the syntax detailed within this repository, and would instead require additions to the specification itself, both on a structural and syntatic level.
Below is a proposal for potential extensions I've settled on, after exploring the different possibilities, and some discussion with end users of the plugin. These extensions would make the CriticMarkup syntax functionally on par with the suggestion systems found in Google Docs and Word, and would allow for better interoperability between rich-text formats (related: jgm/pandoc#2873)
Any critiques, comments, ideas, suggestions would be very much appreciated.
EDIT 1: Fix typo's and improved language, changed metadata 'colour' field to 'color', notes on backwards compatibility with previous versions of the standard
EDIT 2: Add links to related issues from this repository related to the design of the extensions and issues it attempts to address, small note about multimarkdown compatibility w.r.t. the metadata separator
EDIT 3: Metadata is now stored in JSON for more reliably parsing, the plugin has now been updated to support the processing of metadata and rendering of adjacent comments as replies
Note
Some nomenclature: {** **} will be used throughout this issue as a shorthand to indicate any Critic marking (i.e. {++ ++}, {-- --}, {~~ ~> ~~}, {>> <<}, {== ==})
Note
The extensions below have been designed with backwards compatibility in mind, the extended markup will still render properly in editors that do not support these extensions
Replies
Concept
For enabling collaborative editing with other people, the user would want to be able to reply to comments and suggestions made within the program.
This solution addresses points brought up in #35.
Proposal
Any comments directly adjacent to suggestions and comments, will be considered as 'replies' to said suggestion or comment.
In general, the structure would look something like:
{** SUGGESTION **}{>> REPLY <<}
Some examples:
This is some {++added++}{>>reply 1<<} text
Lorem ipsum {>>a comment<<}{>>reply 1<<}{>>reply 2<<}
Some words being {--removed--}{>>reply 1<<}{++added++}{>>reply 1<<}
Important
Any whitespaces between the brackets (i.e. {>>a comment<<} {>>reply 1<<}), will result in the two markings to be considered as separate entities again.
Note
This behaviour is modelled after the {==highlight==}{>>comment<<} structure. With these extensions, this too can be extended as: {==highlight==}{>>comment<<}{>>reply 1<<}.
EDIT: According to #34, this behaviour was planned from the start, though it does not seem to be codified yet. There is no mention either of how replies would work.
Custom Metadata
Concept
The markup itself only specifies information on what type of marking should be applied. However, the user might want to be able to add more information about each individual marking, similar to how YAML frontmatter functions in markdown documents.
This metadata for comments and suggestions can in turn be used to denote the following:
- Author: e-mail, unique identifier, name, ... for the person who created the comment and suggestion
- Timestamp: UNIX timestamp for when the suggestion/comment was made
- Completedness: A boolean value indicating whether a suggestion/comment has been accepted
- ...
Editors may use this metadata to display the suggestion/comment in a particular way, allow filtering, additional processing, etc.
This solution addresses points brought up in #17.
Proposal
At the start of each marking's contents, a JSON object containing arbitrary information may be added for simple and cross-platform parsing.
Specifically, this means that when adding a separator (@@ chosen for this particular example) between the metadata and the contents, the editor can parse all the contents before as metadata:
{** METADATA @@ CONTENTS **}
And a specific example of the metadata:
{++{"type1":"abcdefg", "type2":1234.56, "type3":[1, 2, 3]} @@ an addition with metadata++}
Important
If the editor supports it, the metadata should be hidden to the user by default. This reduces the amount of noise within the text, and prevents malformation of the metadata due to accidental edits
Warning
A suitable notation is required for the metadata separator. This should be a string of characters that is:
- easy to type on a variety of keyboard layouts (symbols like
é,¤, ... only exist in a small subset of keyboards or require multiple keypresses to type) - does not conflict with existing markdown syntax (i.e.:
**,$$, ...) - is not something the user would often type (
&&,<>, ...)
For the moment, @@ seems to be a reasonably good separator string that fits above criteria, though this has not been tested rigorously yet. However, it does not seem to conflict with any of the existing MultiMarkdown syntax
In addition, I would also like to propose some basic metadata types, such that these markings are interoperable between editors:
author:"Fevol"(string, denotes author of marking)time:1695214491(UNIX timestamp, when the marking was made)done:true(boolean, whether the marking is considered completed)color:"2F81F7"(hex code, for highlights specifically: which colour the highlight should have)style:"my-custom-class"(string, additional CSS class that is applied to the marking)
If the names of these metadata fields are deemed to be too long, a shorthand notation could be used instead for some of the most important fields:
{>>{"author":"Fevol","time":1695214491}@@comment<<}
{>>{"a":"Fevol","t":1695214491}@@comment<<}