build: prevent markdown styling from bleeding into examples

Currently we style the content in the docs by setting a `docs-markdown` class around it which then targets element tags that can be produced by the markdown renderer like `p` and `h1`. The problem with this is that some components use these elements for their own styling, e.g. the main `mat-card` example looks off because its `p` tag styling is overridden by `docs-markdown`.

These changes update the docs generation script to exclude the component styles from the markdown styles.

Author: crisbeto

tools/markdown-to-html/docs-marked-renderer.ts

@@ -4,6 +4,12 @@ import {basename, extname} from 'path';
 /** Regular expression that matches example comments. */
 const exampleCommentRegex = /<!--\s*example\(\s*([^)]+)\)\s*-->/g;
 
+/** Marker inserted before the start of an example. */
+const exampleStartMarker = '<!-- ___exampleStart___ -->';
+
+/** Marker inserted after the end of an example. */
+const exampleEndMarker = '<!-- ___exampleEnd___ -->';
+
 /**
  * Custom renderer for marked that will be used to transform markdown files to HTML
  * files that can be used in the Angular Material docs.
@@ -85,11 +91,11 @@ export class DocsMarkdownRenderer extends Renderer {
           file: string;
           region: string;
         };
-        return `<div material-docs-example="${example}"
+        return `${exampleStartMarker}<div material-docs-example="${example}"
                              ${file ? `file="${file}"` : ''}
-                             ${region ? `region="${region}"` : ''}></div>`;
+                             ${region ? `region="${region}"` : ''}></div>${exampleEndMarker}`;
       } else {
-        return `<div material-docs-example="${content}"></div>`;
+        return `${exampleStartMarker}<div material-docs-example="${content}"></div>${exampleEndMarker}`;
       }
     });
 
@@ -120,6 +126,16 @@ export class DocsMarkdownRenderer extends Renderer {
     this._slugger.seen = {};
     this._referencedFragments.clear();
 
-    return `<div class="docs-markdown">${output}</div>`;
+    const markdownOpen = '<div class="docs-markdown">';
+
+    // The markdown styling can interfere with the example's styles, because we don't use
+    // encapsulation. We work around it by replacing the opening marker, left by the previous
+    // step, with a closing tag, and replacing the closing marker with an opening tag.
+    // The result is that we exclude the example code from the markdown styling.
+    output = output
+      .replace(new RegExp(exampleStartMarker, 'g'), '</div>')
+      .replace(new RegExp(exampleEndMarker, 'g'), markdownOpen);
+
+    return `${markdownOpen}${output}</div>`;
   }
 }