search

joeyespo / grip

Preview GitHub README.md files locally before committing them.
MIT License
6.45k stars 423 forks source link

Support for markdown comments #250

Open strobelight opened 6 years ago

strobelight commented 6 years ago

I found somewhere the following works as comments in some markdown renderers:

[//]: # (This syntax works like a comment, and won't appear in any output.)
[//]: # (It’s a little bizarre, but it works with MacDown and Pandoc and strapdown.js.)

I have no clue on the magic behind it, just found somewhere online and it worked. I have the strapdown.js as a cgi-bin handler for .md files to render them in browsers that support javascript but not markdown.

It would be great to check my .md files while writing and include comments.

thorr18 commented 6 years ago

For me, it works in grip already and on github. (unless it's in a code block)

Foo
Comment to follow, this line shows and the required blank line will also display:

[//]: # (This syntax works like a comment, and won't appear in any output.)
Comment done. This line is displayed after the required blank line.
Bar

Foo Comment to follow, this line shows and the required blank line will also display:

Comment done. This line is displayed after the required blank line. Bar

init-js commented 6 years ago

You can indeed comment text with [//]: # (commented out stuff), but in addition to the context where your comment can appear (like @thorr18 mentions), you are also restricted in the content that is contained within the ( ).

For instance, 

[//]: # ( [old link](./FOO.md))

will still get rendered:

So, really this approach of commenting is really only suitable for personal notes. If you're trying to comment out markdown code (which you would, in README-driven-development), then I agree with @strobelight that a better commenting approach would be needed.

the magic behind it is that "#" is a URL to an empty anchor. And that [//]: is the syntax to add your references in a different location than the place where the link is seen in the text (usually those are packed at the end of a document) -- those aren't displayed until you "cite" them. The // is just a visual indication to the reader of the raw markdown file that this is intended as a comment. You could replace // with rem or ignore, and it would be the same.