Comments

[lvansnippenburg]

WHen trying to use markdown in the flow of knowledge, thoughts, annotations and final writing, comments should also be considered. Work is reviewed (or should be reviewed by co-workers and supervisors. MS Word has nice features for this, but who wants to use Word? Looking around for comments in markdown I found several workarounds, of which I found one promising. Here is a piece of markdown discussing the options and a possible good workaround that mimics what we know from Word. Please note that as some text is in comments, it will not be shown in the Preview of Github and you'll have to switch to display raw text.

Comments in markdown

The easiest is to just use HTML comments like this: . Of course you see nothing in the preview, as the comment is not rendered, which is great.

A second method it to create it as a markdown comment, with empty lines before and after it.

A third alternative might be to put the comment in square brackets, again this option doesn't work when the comment is inline.

So of these options the HTML comment option seems to be the best!

Please let me know if you have any further questions, but I guess we have all used the MS Word function for remarks.

Kind regards,
Leo

[lvansnippenburg]

Just in case: Here is the plain version in a codeblock:

### Comments in markdown

The easiest is to just use HTML comments like this: <!-- here is a comment -->. Of course you see nothing in the preview, as the comment is not rendered.

A second method it to create it as a markdown comment

[comment]: # (and here comes the actual comment)

But what happens when it is inline? It won't work, whereas normal HTML comments do work. (remove the blank line afer this line)

[//]: # (This may be the most platform independent comment)

A third alternative might be to put the comment in square brackets, again this option doesn't work when the comment is inline. [this is inline] ::

[This is on a separate line]::

So of these options the HTML comment option seems to be the best! <!-- as it can also be used inline, and support any number of lines or characters. -->

<!-- LvS:: Now we need agreement on the format of the content of the remark. My suggestion is to have the editor's initials, then double semi-column, followed by the actual comment. In the previes this should be rendered as it is in word, with a text-balloon and the comment displayed when clicked on it. A more extended version could be to do it as a JSON object, enabling discussions even. Something like this: 

{remarks: [{author: "LvS", time: 060520261556, text: "this is my remarkt to this passage of text."},{author: "PE", time: 060520261743, text: "My explanation for your remark."}], done: false}

For a more readable version yaml could be considered:

remarks:
  - author: LvS
    time: "060520261556"
    text: this is my remarkt to this passage of text.
  - author: PE
    time: "060520261743"
    text: My explanation for your remark.
done: false

In either case, the advatage of this approach is that the remark will stay in the text position to which it applies, also when text is added or removed in other areas of the document.
-->