[{"data":1,"prerenderedAt":66},["Reactive",2],{"blog-post-how-to-add-comments-in-markdown":3},{"slug":4,"title":5,"description":6,"excerpt":7,"date":8,"category":9,"author":10,"keywords":11,"readingMinutes":12,"html":13,"headings":14,"tools":40,"related":42},"how-to-add-comments-in-markdown","How to Add Comments in Markdown: A Complete Guide","Learn different methods to add comments in Markdown files. Discover HTML comments, invisible text techniques, and best practices for documentation.","Comments in Markdown are essential for adding notes, reminders, or explanations that won't appear in the rendered output. Unlike many programming languages, Markdown doesn't have native comment…","2025-08-02","Tutorial","Matthew Rathbone","comments in markdown, markdown comments, how to comment markdown",4,"\u003Cp>Comments in Markdown are essential for adding notes, reminders, or explanations that won't appear in the rendered output. Unlike many programming languages, Markdown doesn't have native comment syntax, but there are several effective methods to achieve this functionality.\u003C/p>\n\u003Cp>In this tutorial, we'll explore different ways to add comments to your Markdown files, from HTML comments to creative workarounds.\u003C/p>\n\u003Ch2 id=\"method-1-html-comments-most-common\">Method 1: HTML Comments (Most Common)\u003C/h2>\n\u003Cp>The most widely supported method for adding comments in Markdown is using HTML comment syntax. Since Markdown supports HTML, these comments work across virtually all Markdown processors.\u003C/p>\n\u003Ch3 id=\"basic-html-comment-syntax\">Basic HTML Comment Syntax\u003C/h3>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\"><!-- This is a comment in Markdown -->\n\u003C/code>\u003C/pre>\u003Cp>HTML comments use the \u003Ccode><!--\u003C/code> to start and \u003Ccode>-->\u003C/code> to end the comment. Everything between these tags will be invisible in the rendered output.\u003C/p>\n\u003Ch3 id=\"multi-line-html-comments\">Multi-line HTML Comments\u003C/h3>\n\u003Cp>You can create multi-line comments for longer notes:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\"><!--\nThis is a multi-line comment\nthat spans several lines.\nPerfect for detailed notes or documentation.\n-->\n\u003C/code>\u003C/pre>\u003Ch3 id=\"example-in-context\">Example in Context\u003C/h3>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-section\"># My Document Title\u003C/span>\n\n<!-- TODO: Add more examples here -->\n\nThis is visible text that will appear in the rendered output.\n\n<!-- \nAuthor notes:\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> Need to verify all links\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> Add screenshots later\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> Review for grammar\n-->\n\nMore visible content continues here.\n\u003C/code>\u003C/pre>\u003Ch2 id=\"method-2-reference-style-links-creative-approach\">Method 2: Reference-Style Links (Creative Approach)\u003C/h2>\n\u003Cp>Another approach is using reference-style link syntax with undefined references. These won't render as links since the references don't exist.\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">[\u003Cspan class=\"hljs-symbol\">//\u003C/span>]: \u003Cspan class=\"hljs-link\"># "This is a comment using reference links"\u003C/span>\n[\u003Cspan class=\"hljs-symbol\">//\u003C/span>]: \u003Cspan class=\"hljs-link\"><> (This is another comment style)\u003C/span>\n\u003C/code>\u003C/pre>\u003Ch3 id=\"example-usage\">Example Usage\u003C/h3>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">[\u003Cspan class=\"hljs-symbol\">//\u003C/span>]: \u003Cspan class=\"hljs-link\"># "Remember to update this section before publishing"\u003C/span>\n\n\u003Cspan class=\"hljs-section\"># Getting Started\u003C/span>\n\nThis section explains the basics...\n\n[\u003Cspan class=\"hljs-symbol\">//\u003C/span>]: \u003Cspan class=\"hljs-link\"><> (Note: This example needs more detail)\u003C/span>\n\u003C/code>\u003C/pre>\u003Ch2 id=\"method-3-invisible-unicode-characters\">Method 3: Invisible Unicode Characters\u003C/h2>\n\u003Cp>You can use zero-width space characters or other invisible Unicode characters, though this method is less reliable across different platforms.\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">​<!-- This comment uses a zero-width space at the beginning -->\n\u003C/code>\u003C/pre>\u003Cp>\u003Cstrong>Note\u003C/strong>: This method is not recommended as it can cause formatting issues and isn't universally supported.\u003C/p>\n\u003Ch2 id=\"method-4-blockquotes-for-visible-notes\">Method 4: Blockquotes for Visible Notes\u003C/h2>\n\u003Cp>While not true comments, you can use blockquotes for notes that should be visible but distinguished from main content:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-quote\">> \u003Cspan class=\"hljs-strong\">**Note**\u003C/span>: This is a visible comment that appears in the rendered output\u003C/span>\n\u003Cspan class=\"hljs-quote\">> but is visually distinct from the main text.\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>This renders as:\u003C/p>\n\u003Cblockquote>\n\u003Cp>\u003Cstrong>Note\u003C/strong>: This is a visible comment that appears in the rendered output\u003Cbr>but is visually distinct from the main text.\u003C/p>\n\u003C/blockquote>\n\u003Cp>For more information on blockquotes, check out our comprehensive \u003Ca href=\"/blog/guide-to-blockquotes-in-markdown\">guide to blockquotes in Markdown\u003C/a>.\u003C/p>\n\u003Ch2 id=\"best-practices-for-markdown-comments\">Best Practices for Markdown Comments\u003C/h2>\n\u003Ch3 id=\"1-use-html-comments-for-true-comments\">1. Use HTML Comments for True Comments\u003C/h3>\n\u003Cp>When you need comments that are completely invisible in the output, stick with HTML comment syntax:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\"><!-- This won't appear in the rendered version -->\n\u003C/code>\u003C/pre>\u003Ch3 id=\"2-be-descriptive\">2. Be Descriptive\u003C/h3>\n\u003Cp>Write clear, descriptive comments that explain the purpose:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\"><!-- Section for user authentication examples - update after API changes -->\n\u003C/code>\u003C/pre>\u003Ch3 id=\"3-use-comments-for-todos-and-reminders\">3. Use Comments for TODOs and Reminders\u003C/h3>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\"><!-- TODO: Add code example for error handling -->\n<!-- FIXME: This section needs better organization -->\n<!-- NOTE: Double-check these statistics before publishing -->\n\u003C/code>\u003C/pre>\u003Ch3 id=\"4-comment-out-sections-temporarily\">4. Comment Out Sections Temporarily\u003C/h3>\n\u003Cp>Use comments to temporarily remove content without deleting it:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\"><!--\n\u003Cspan class=\"hljs-section\">## Section Under Review\u003C/span>\n\nThis entire section is temporarily hidden\nwhile we verify the accuracy of the information.\n-->\n\u003C/code>\u003C/pre>\u003Ch2 id=\"platform-specific-considerations\">Platform-Specific Considerations\u003C/h2>\n\u003Ch3 id=\"github-markdown\">GitHub Markdown\u003C/h3>\n\u003Cp>GitHub-flavored Markdown fully supports HTML comments, making them invisible in rendered files, issues, and pull requests.\u003C/p>\n\u003Ch3 id=\"static-site-generators\">Static Site Generators\u003C/h3>\n\u003Cp>Most static site generators (Jekyll, Hugo, Gatsby) preserve HTML comments in the source but strip them from the final HTML output.\u003C/p>\n\u003Ch3 id=\"documentation-platforms\">Documentation Platforms\u003C/h3>\n\u003Cp>Platforms like GitBook, Notion, and Confluence handle HTML comments differently:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Cstrong>GitBook\u003C/strong>: Comments are hidden in rendered output\u003C/li>\n\u003Cli>\u003Cstrong>Notion\u003C/strong>: Limited HTML support\u003C/li>\n\u003Cli>\u003Cstrong>Confluence\u003C/strong>: Comments may appear depending on settings\u003C/li>\n\u003C/ul>\n\u003Ch2 id=\"common-pitfalls-to-avoid\">Common Pitfalls to Avoid\u003C/h2>\n\u003Ch3 id=\"1-nested-comments\">1. Nested Comments\u003C/h3>\n\u003Cp>HTML doesn't support nested comments, so avoid this:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\"><!-- This is a comment <!-- This nested comment will break things --> -->\n\u003C/code>\u003C/pre>\u003Ch3 id=\"2-comments-in-code-blocks\">2. Comments in Code Blocks\u003C/h3>\n\u003Cp>Comments inside code blocks will be visible:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\n\u003C/code>\u003C/pre>\u003C!-- This comment will be visible inside the code block -->\n\u003Cpre>\u003Ccode>\n\u003C/code>\u003C/pre>\u003Ch3 id=\"3-special-characters-in-comments\">3. Special Characters in Comments\u003C/h3>\n\u003Cp>Be careful with special characters that might break the comment:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\"><!-- Don't use -- inside comments - it can break the syntax -->\n<!-- Use — instead of -- if needed -->\n\u003C/code>\u003C/pre>\u003Ch2 id=\"conclusion\">Conclusion\u003C/h2>\n\u003Cp>Adding comments to Markdown files is straightforward once you know the right techniques. HTML comments (\u003Ccode><!-- -->\u003C/code>) are the most reliable method, working across virtually all Markdown processors and platforms. \u003C/p>\n\u003Cp>Whether you're documenting code, leaving notes for collaborators, or temporarily hiding content, these comment techniques will help you maintain clean, well-documented Markdown files.\u003C/p>\n\u003Cp>Remember that the visibility of comments depends on your specific Markdown processor and rendering platform, so always test your comments in your target environment to ensure they behave as expected.\u003C/p>\n\u003Cp>You can test all these comment techniques immediately in the \u003Ca href=\"/tools/markdown-editor\">Markdown Live Editor\u003C/a> — paste your Markdown with comments and see exactly what renders and what stays hidden.\u003C/p>\n",[15,19,22,25,28,31,34,37],{"id":16,"text":17,"level":18},"method-1-html-comments-most-common","Method 1: HTML Comments (Most Common)",2,{"id":20,"text":21,"level":18},"method-2-reference-style-links-creative-approach","Method 2: Reference-Style Links (Creative Approach)",{"id":23,"text":24,"level":18},"method-3-invisible-unicode-characters","Method 3: Invisible Unicode Characters",{"id":26,"text":27,"level":18},"method-4-blockquotes-for-visible-notes","Method 4: Blockquotes for Visible Notes",{"id":29,"text":30,"level":18},"best-practices-for-markdown-comments","Best Practices for Markdown Comments",{"id":32,"text":33,"level":18},"platform-specific-considerations","Platform-Specific Considerations",{"id":35,"text":36,"level":18},"common-pitfalls-to-avoid","Common Pitfalls to Avoid",{"id":38,"text":39,"level":18},"conclusion","Conclusion",[41],"markdown-editor",[43,51,58],{"slug":44,"title":45,"description":46,"excerpt":47,"date":48,"category":9,"author":10,"keywords":49,"readingMinutes":50},"markdown-annotations-comments-complete-guide","Markdown Annotations and Comments: Complete Guide for Technical Documentation","Master Markdown annotations and comments for professional technical documentation. Learn platform-specific implementations, code annotations, editorial comments, and collaborative review workflows for enhanced content development.","Markdown annotations and comments enable sophisticated documentation workflows that separate content from editorial notes, facilitate collaborative review processes, and provide context for…","2025-09-10","markdown annotations, markdown comments, technical documentation comments, markdown editorial notes, code annotations markdown, collaborative writing markdown, documentation review process",25,{"slug":52,"title":53,"description":54,"excerpt":54,"date":55,"category":9,"author":56,"keywords":57,"readingMinutes":18},"add-table-of-contents-to-markdown-using-javascript","Add table of contents to markdown using JavaScript","A table of contents, or TOC, is a useful navigation tool for long documents, allowing readers to quickly jump to different sections of the text. In markdown, a lightweight markup language used for…","2023-01-10","Matthew Rathbone (with help from OpenAI)","5/31/2023",{"slug":59,"title":60,"description":61,"excerpt":62,"date":63,"category":9,"author":10,"keywords":64,"readingMinutes":65},"how-to-add-line-numbers-to-code-blocks-in-markdown","How to Add Line Numbers to Code Blocks in Markdown: Complete Guide","Learn how to display line numbers in Markdown code blocks using GitHub, Jekyll, Hugo, and other platforms. Includes syntax highlighting and customization options.","Line numbers in code blocks significantly improve code readability and make it easier to reference specific lines in documentation, tutorials, and code reviews. While standard Markdown doesn't…","2025-08-13","markdown line numbers, code block line numbers, markdown syntax highlighting, numbered code blocks, markdown programming examples",6,1792184940755]