feat(comments): add docs for markdown comments (#815)

packages/example/src/pages/components/markdown.mdx

@@ -20,6 +20,7 @@ For most pages, we recommend starting with a `PageDescription` followed by `Anch
   <AnchorLink>Code blocks</AnchorLink>
   <AnchorLink>Tables</AnchorLink>
   <AnchorLink>Blockquotes and citations</AnchorLink>
+  <AnchorLink>Comments</AnchorLink>
 </AnchorLinks>
 
 ## Text decoration
@@ -128,7 +129,7 @@ Strikethrough uses two tildes. ~~Scratch this.~~
 
 [I’m a markdown link](https://www.carbondesignsystem.com)
 
-[I’m a markdown link with title](https://www.carbondesignsystem.com 'Carbon’s Homepage')
+[I’m a markdown link with title](https://www.carbondesignsystem.com "Carbon’s Homepage")
 
 URLs and URLs in angle brackets will automatically get turned into links.
 http://www.example.com or <http://www.example.com> and sometimes
@@ -139,7 +140,7 @@ example.com (but not on Github, for example).
 ```markdown src=https://github.com/carbon-design-system/gatsby-theme-carbon/tree/master/packages/gatsby-theme-carbon/src/components/markdown
 [I’m a markdown link](https://www.carbondesignsystem.com)
 
-[I’m a markdown link with title](https://www.carbondesignsystem.com 'Google’s Homepage')
+[I’m a markdown link with title](https://www.carbondesignsystem.com "Google’s Homepage")
 
 [I’m a local link](/components/demo)
 
@@ -245,3 +246,17 @@ raw Markdown line up prettily. You can also use inline Markdown.
 >
 > <cite>– Paul Rand</cite>
 ```
+
+## Comments
+
+Comments can be added that will not display on the page, but will be visible in the markdown source.
+
+<!-- Comments like this are visible in code, but are not visible on the page -->
+
+### Code
+
+```markdown src=https://github.com/carbon-design-system/gatsby-theme-carbon/tree/master/packages/gatsby-theme-carbon/src/components/markdown
+Comments can be added that will not display on the page, but will be visible in the markdown source.
+
+<!-- Comments like this are visible in code, but are not visible on the page -->
+```