· 6 min read

Comments in Markdown

Learn how to add comments in Markdown using HTML-style comments, code blocks, and best practices for collaboration, clarity, and organization in GitHub, GitLab, and static site generators.

Learn how to add comments in Markdown using HTML-style comments, code blocks, and best practices for collaboration, clarity, and organization in GitHub, GitLab, and static site generators.

Markdown is a popular lightweight markup language used for formatting text. Although Markdown is primarily used for writing content, it lacks a native syntax for comments, unlike programming languages. However, you can still add comments using a few workarounds. Comments are useful for leaving notes, reminders, or instructions that are not rendered in the final output.

In this article, I’ll explain different ways to add comments in Markdown, including single-line comments, multi-line comments, using comments in code blocks, and leveraging HTML comments. We’ll also cover specific practices for using comments in GitHub and GitLab Markdown.

Using HTML Comments in Markdown

The most common and versatile way to add comments in Markdown is by using HTML-style comments. Since Markdown supports HTML, you can use the standard HTML comment syntax to insert comments. These comments will not be displayed when the Markdown file is rendered.

HTML Comment Syntax:

<!-- This is a comment -->

Single-Line Comments:

To add a single-line comment in Markdown, use the HTML comment syntax. This method works across all Markdown processors, making it a reliable choice.

Example:

<!-- This is a single-line comment -->
This text will be rendered in the final output.

In this example, the comment <!-- This is a single-line comment --> will not be visible in the rendered output, but the text This text will be rendered in the final output. will be.

Multi-Line Comments:

Multi-line comments can also be created using the same HTML comment syntax. Just wrap your comments in <!-- and --> and span them across multiple lines.

Example:

<!--
This is a multi-line comment.
It spans multiple lines and is not displayed in the rendered output.
-->
This text is outside the comment and will be displayed.

Everything between <!-- and --> is considered a comment and will not appear in the final rendered output. This method is useful for writing detailed notes or instructions within your Markdown files.

Comments in Code Blocks:

Markdown allows the inclusion of code blocks, which are useful for displaying code snippets. You can also include comments within these code blocks. The syntax for comments within code blocks depends on the language of the code.

Commenting in Different Languages:

  1. JavaScript Code Block Example:

    // This is a single-line comment in JavaScript
    console.log("Hello, World!"); // Inline comment
    /* This is a
        multi-line comment in JavaScript */

  2. Python Code Block Example:

    # This is a single-line comment in Python
    print("Hello, World!")  # Inline comment
    '''
    This is a multi-line comment
    in Python.
    '''

  3. HTML Code Block Example:

    ```html
    <!-- This is a comment in HTML -->
    <p>This paragraph is visible.</p>

These comments will be visible in the code block in the rendered output, as they are part of the displayed code. This is particularly useful for documentation purposes, where you want to explain specific parts of the code.

Using Comments in GitHub and GitLab Markdown

GitHub and GitLab are popular platforms for hosting code repositories, and both support Markdown for writing documentation, issues, and comments. The use of comments in these environments helps developers and collaborators leave notes without affecting the final presentation of the document.

GitHub Markdown Comments:

GitHub supports HTML comments in Markdown files, making it easy to hide content from the rendered view. These comments can be used in README files, issues, pull requests, and wikis.

Example:

<!-- This is a GitHub-specific comment -->
# Project Title


<!-- This section is under development -->
## Coming Soon: New Features

The comment <!-- This is a GitHub-specific comment --> and <!-- This section is under development --> will not appear in the rendered Markdown file on GitHub, providing a way to leave notes for collaborators.

GitLab Markdown Comments:

Like GitHub, GitLab also supports HTML comments in Markdown. You can use the same syntax to include comments in GitLab’s README files, wikis, issues, and merge requests.

Example:

<!-- This is a GitLab-specific comment -->
# Welcome to the Project


<!-- Temporary note: Remember to update the documentation -->
## Documentation

These comments will be hidden in the rendered output on GitLab, allowing you to include remarks or reminders for your team.

Markdown Tools and integrations With Comment Support

There are many tools and integrations that support Markdown comments. Here are a few examples:

  • Markdown editors and IDEs - Many Markdown editors and IDEs, such as Visual Studio Code, Atom, and Sublime Text, support comments and provide features like syntax highlighting and auto-completion.

  • Comment-enabled Markdown plugins - Plugins like Markdown-it and Remark provide comment support and can be integrated into static site generators like Jekyll or Hugo.

Best Practices for Using Comments in Markdown

  • Keep Comments Relevant - Use comments to add context, explanations, or reminders that are relevant to the content. Avoid cluttering your Markdown files with unnecessary comments.

  • Use HTML Comments for Markdown - Since Markdown does not have a native comment syntax, HTML comments (<!-- comment -->) are the best choice for hiding content across different Markdown processors.

  • Document Code Blocks Clearly - When including code blocks, use language-specific comment syntax to provide explanations directly within the code. This helps readers understand the purpose and functionality of the code.

  • Be Aware of Rendering Differences - Different platforms and static site generators might handle Markdown and HTML comments differently. Always check how your comments render in the specific environment you are using.

  • Keep Comments Up-to-Date - Regularly review and update comments to ensure they remain accurate and relevant. Outdated comments can lead to confusion and misinterpretation.

Security considerations

Comments can pose security risks if not handled properly. Here are some security considerations:

  • Comment injection attacks - Malicious users can inject comments that contain malicious code, which can be executed when the Markdown file is rendered.
  • Data exposure - Comments can contain sensitive information, such as API keys or passwords, which can be exposed if not properly sanitized.
  • Best practices for sanitizing user-input comments - To mitigate these risks, it’s essential to sanitize user-input comments and ensure that they do not contain malicious code or sensitive information.

Conclusion

While Markdown doesn’t have a built-in comment syntax, using HTML-style comments is a practical and widely supported solution. Whether you’re working on GitHub, GitLab, or a static site generator, comments can help improve collaboration, provide clarity, and keep your documentation organized. By following best practices and understanding how to use comments effectively, you can enhance the readability and maintainability of your Markdown files.

    Share:
    Back to Blog