Markdown is a lightweight markup language that allows you to create formatted text using plain text syntax. One of the essential features of any markup language is the ability to add comments, which are notes or explanations that are not rendered in the final output. In this tutorial, we will explore how to write comments in Markdown.
Using Link Labels
One way to write comments in Markdown is to use link labels. Link labels are used to define links that can be referenced later in the document. You can use this feature to create comments by defining a link label with no actual link. The syntax for this is as follows:
[comment]: # (This is a comment)
The # symbol is used instead of an actual link, and the text inside the parentheses is your comment. This method is platform-independent and works with most Markdown parsers.
Using HTML Comments
Another way to write comments in Markdown is to use HTML comments. HTML comments are not rendered by browsers and can be used to add notes or explanations to your Markdown document. The syntax for HTML comments is as follows:
<!---
your comment goes here
and here
-->
Note that the triple dash --- is used instead of the usual -- to ensure compatibility with some Markdown parsers.
Using Liquid Tags (Jekyll and Octopress)
If you are using Jekyll or Octopress, you can use Liquid tags to write comments. Liquid tags are parsed first and removed before the Markdown processor even gets to it, making them invisible to visitors. The syntax for this is as follows:
{% comment %}
These comments will not include inside the source.
{% endcomment %}
Best Practices
When writing comments in Markdown, it’s essential to follow best practices to ensure compatibility and readability. Here are some tips:
- Use an empty line before and after your comment to ensure that it is not rendered incorrectly by some Markdown parsers.
- Use the
#symbol instead of an actual link when using link labels to create comments. - Avoid using excluded-on-render comments with certain implementations, such as cebe/markdown 1.1.0, cebe/markdown MarkdownExtra 1.1.0, and s9e\TextFormatter (Fatdown/PHP).
By following these tips and using the methods outlined in this tutorial, you can effectively write comments in Markdown and keep your documents organized and readable.