Everything You Need to Know About Markdown Comments

Markdown has become one of the most popular lightweight markup languages used across the web. With its simple syntax that is easily converted to HTML, Markdown makes it straightforward for anyone to write formatted text.

One key feature that Markdown lacks out-of-the-box is support for comments. However, over the years clever solutions have emerged to allow comments in Markdown documents.

In this comprehensive guide, we will cover everything you need to know about Markdown comments:

What is Markdown?

Markdown was created in 2004 by John Gruber as a simple way to write formatted text that could easily be converted to XHTML or HTML. The key design goals of Markdown were:

• Readability – Markdown should be readable as-is, without looking like tagged up text
• Writeability – Markdown syntax needs to be easy to write and read naturally
• Plain text convertibility – Markdown text should be able to be converted to structurally valid XHTML or HTML

With these goals in mind, Gruber designed Markdown using a simple syntax that builds upon conventions from plain text email and uses intuitive punctuation characters. For example, asterisks around text are used to denote italics and pound signs precede headings.

Markdown has seen widespread adoption across the web and is supported by countless applications and websites. It strikes the perfect balance between human readability and machine convertibility.

Why Use Comments in Markdown?

Although Markdown excels at readable text, it does not have native support for comments. You may be wondering why comments are even necessary in Markdown. Here are some common use cases:

Notes for self while writing – When drafting Markdown documents, authors often want to leave notes or comments to themselves that won‘t appear in the final rendered output.

Context for readers – Writers may want to leave commentary to provide background or context to readers about why certain decisions were made.

Disabled content – Occasionally content needs to be disabled or omitted without deleting it entirely. Markdown comments allow text to be retained but not rendered.

Code commenting – Within Markdown code blocks, comments are indispensable for documenting and annotating code.

Metadata comments – Some static site generators allow Markdown metadata and front matter config to be commented for better readability.

As you can see, although Markdown itself is quite simple, comments enable a wide range of useful functionality for Markdown authors.

Markdown Comment Syntaxes

Since native Markdown does not support comments, various unofficial conventions have emerged over the years to allow commenting. Different parsers and tools support different syntaxes. Let‘s explore the most common Markdown comment formats:

Square Bracket Colon Pound

[comment text here]: #

This format encloses the comment text in square brackets, followed by a colon and pound sign. For example:

Here is some Markdown text
[This paragraph explains my reasoning]: #
With a comment that will not appear

Many Markdown parsers such as Markdown.pl support this simple syntax. However, it can occasionally cause unintended issues with some parsers when the comment text itself contains colons or equals signs.

Square Brackets Slashes Pound

[//]: # (comment text here)

This syntax wraps the comment in square brackets, followed by a double slash and pound sign indicator, with the comment text surrounded in parentheses. For example:

Here is some Markdown text
[//]: # (Here is a hidden comment)
That will render normally

This format is widely supported and avoids issues with comment text being interpreted accidentally. A variation uses double quotes around the comment:

[//]: # "Comment here"

Square Brackets Pound

[]: # (comment)

Some parsers allow comments with just an open and closed square bracket, colon and pound sign, omitting the double slashes. For example:

Here is some text
[]: # (With a hidden comment)  
That will render

HTML Comments

Markdown allows raw HTML, so HTML comments can also be inserted:

Here is some text
<!-- This is an HTML comment -->
That will render

Multi-line HTML comments are also allowed:

Some text

<!-- 
This is a 
multi-line 
comment
-->

More text

The downside to HTML comments is they are not as portable for non-HTML output, like PDF.

Github Fenced Comment Blocks

Github flavored Markdown includes an additional syntax for fenced comment blocks:

Here is some text

{::comment}
This Github style 
multi-line 
comment 
will not render
{:/comment}

More text

However, this is a proprietary Github convention that is not portable to other parsers.

As you can see, while native Markdown has no comment syntax, numerous conventions have emerged over the years. The most portable options are the square bracket slash pound and HTML comment formats.

Top Markdown Parsers

With an understanding of Markdown comment syntax, let‘s explore some of the most popular Markdown parsers and their comment support:

Markdown.pl

This Perl-based script was the original Markdown parser created by John Gruber himself. It pioneered the square bracket colon pound comment syntax and remains one of the most simple and portable options to this day.

Kramdown

Kramdown is a popular Markdown parser for Ruby and Ruby on Rails projects. It is strict about following the original Markdown syntax but does allow square bracket colon pound comments.

CommonMark

CommonMark is an effort to standardize Markdown syntax across parsers. The latest CommonMark specification does not include any comment formats, but most CommonMark parsers allow HTML comments.

Github Flavored Markdown (GFM)

GFM extends basic Markdown with some additional conventions, like fenced code blocks and fenced comment blocks outlined earlier. Of course, these Github extensions may not port to other platforms.

Python Markdown

Python Markdown is a full-featured Markdown parser for Python. It is very configurable and allows custom extensions. Both HTML comments and square bracket colon pound comments are supported out of the box.

Markdown Here

Markdown Here provides a popular browser-based Markdown editor. It utilizes the Showdown JavaScript parser which supports both HTML comments and square bracket slash pound comments.

As you can see, while comment support details vary, most major Markdown parsers allow some convention for including comments, with HTML comments being the most universal.

How Markdown Engines Convert Comments

To understand how Markdown comments work under the hood, we need to explore briefly how Markdown converters process an MD document:

1. Lexing – The lexer tokenizes the Markdown text into discrete elements like headings, code blocks, links, etc

2. Syntax tree – The parser takes the tokens from lexing and builds an abstract syntax tree describing the structure of the document.

3. Rendering – Finally, the renderer traverses the syntax tree and outputs formatted HTML.

Markdown comments work because the lexer and syntax tree stages essentially ignore text flagged as comments. So it never reaches the final render output.

Different Markdown libraries handle this process a bit differently but this is the essential flow that enables comments to be excluded from final rendered content.

Markdown Comment Best Practices

Now that you understand how Markdown comments work, let‘s explore some best practices when working with them:

• Use widely supported syntax – Stick to the most universal comment formats like HTML comments or square bracket slash comments when possible for maximum portability.

• Don’t over-comment – Resist the urge to add trivial comments for every element. Only comment where necessary to augment meaning.

• Keep comments professional – Even internal comments could someday become public. Write comments you would be comfortable sharing.

• Place comments judiciously – Add comments above the content they relate to for easier contextualization. Don‘t comment mid-content without good reason.

• Check rendering – After writing comments, verify they are not rendered in HTML output or exports to avoid accidental disclosure.

Adhering to these best practices will ensure you implement Markdown comments effectively and avoid some common pitfalls.

Other Hidden Content Approaches

In addition to comments, there are a few other techniques in Markdown to selectively exclude content from final rendered output:

Metadata

Many static site generators like Jekyll allow YAML front matter metadata that is stripped out of final content. This metadata can configure site variables or include internal comments:

---
layout: post
author: John Smith
# This post is about Markdown comments 
---

Post content goes here...

The metadata between the triple dashes will not render but can contain hidden author notes.

HTML Comments

As outlined earlier, HTML comments can be used not just for typical comments but also to wrap entire sections of content to exclude them:

<--
This whole block 
will not render
-->

Conditional Include Directives

Static site generators sometimes allow conditional include directives like {% comment %} to wrap content that should be omitted when rendered.

So in addition to typical comments, other techniques like front matter metadata or conditional includes can also help selectively show or hide content as needed.

Conclusion

Being able to comment within Markdown opens up a world of possibilities, from author annotations to disabled content sections. While native Markdown does not support it, luckily conventions have emerged enabling Markdown authors to comment their documents.

Now you have a comprehensive understanding around how to effectively comment Markdown, from syntax formats to parser support down to inner workings under the hood. So take advantage of comments to augment your Markdown content while keeping private notes and context.

What hidden gems have you uncovered in Markdown comments before? Share your discoveries! With the power of Markdown comments, an extra layer of meaning awaits in your documents.