Items

on_markdown.md

Table of Content

• Table of Content
• Examine the markdown guide
• inline comment in markdown
• Reference List in markdown
• Reference List

Examine the markdown guide

There's a magnificent and extensive documentation effort in The Markdown Guide. It is possible the items handled in this gist, have already been documented there, and this gist could be obsolete, apart from the referral.

Insert comment in markdown code

To enter comments in a markdown file (which then only serve as comment to the markdown code) and not as comment in the "formatted output", one can mis-use the definition of references.

This was risen to my attention in a StackExchange post on comment in markdown amd later even more elaborated on this James's knowledge graph.

Define a dummy reference named //, each time again the same reference, and refer it to the target #, and add an additional description to the link (between perenthesis). The description is the actual comment.

    [//]: # ( these comment liens - as formatted in this gist - appear in the preview )
    [//]: # ( however were they inserted as not-quoted, they would not. )
    [//]: # ( They appear here because they are indented and quoted as text )

Reference List in markdown

In larger (markdown) documents, one may choose to maintain a single list containing all (external) references used in the document. Additionally define all these external links also in a single block.

    ...
    In the document one can introduce a reference to 
    [The first reference][ref-ext-1-describe-first-as-gist]
    as seen here,
    ...
    An additional reference to [The second reference][ref-ext-2-look-around]
    ...
    And later the document can re-use the previous 
    [The first reference][ref-ext-1-describe-first-as-gist].
    ...
    ##  Reference List

    *   [The first reference][ref-ext-1-describe-first-as-gist]
    *   [The second reference][ref-ext-2-look-around]

    [//]: # ( this block only holds definitions for - all - external references )
    [//]: # ( it should not appear in the  then not be output in the visualisation )
    [ref-ext-1-describe-first-as-gist]: https://gist.github.com/
    [ref-ext-2-look-around]: https://letmegooglethat.com/?q=look+around
    [//]: # ( end of the reference definition block )

Indeed as can be seen, the maintenance of such a reference list may merit from a "supporting toolchain" to manage the references.

Define footnotes

In larger documents one may feel the need to annotate the text with some footnotes.

Reference List

• The Markdown Guide
• StackExchange post on comment in markdown
• James's knowledge graph