Choose a mechanism for comments?

[m4rc1e]

Just a suggestion from @tphinney.

[tphinney]

What I was particularly looking for was a means to add comments and even substantial amounts of additional info, that does not end up in the compiled doc in a way that is visible to the average reader, by default.

For some items it would be Very Nice to have more explanation and detail about “why” something is the way it is, which are not visible to normal readers. Not (usually) for secrecy reasons, but because it is distracting or “Too Much Information.”

So, two possible approaches:

1. text that is invisible but still present in the HTML, if somebody looks
2. text that only in the source and does not compile to the actual web page seen by normal users. (But even this is going to be visible to anybody who comes to the source page and forks or the like, so I am not clear it gains much.)

I think (1) is slightly preferable, since (2) doesn’t gain much?

[tphinney]

If one wants to do it in basic Git-compatible Markdown without add-ons, seems this approach is favored (from: https://stackoverflow.com/questions/4823468/comments-in-markdown)

[//]: # "Comment" and [//]: # (Comment) seem to work on a wider variety of implementations, because # is a valid relative URI. GitHub, for example, rejects <>, and the entire line becomes visible. It's also worth noting that link labels often need to be separated from other content by a blank line