refactor: update api for embedded example comments in md docs (#19252)

* update example comment api in md to html renderer

* support for old and new api before docs are updated

* stringify lines to preserve brackets

Co-authored-by: Annie Wang <annieyw@google.com>

Author: annieyw

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

@@ -5,7 +5,7 @@ import {basename, extname} from 'path';
 const whitespaceRegex = /\W+/g;
 
 /** Regular expression that matches example comments. */
-const exampleCommentRegex = /<!--\W*example\(([^)]+)\)\W*-->/g;
+const exampleCommentRegex = /<!--\s*example\(([^)]+)\)\s*-->/g;
 
 /**
  * Custom renderer for marked that will be used to transform markdown files to HTML
@@ -47,17 +47,44 @@ export class DocsMarkdownRenderer extends Renderer {
 
   /**
    * Method that will be called whenever inline HTML is processed by marked. In that case,
-   * we can easily transform the example comments into real HTML elements. For example:
+   * we can easily transform the example comments into real HTML elements.
+   * For example:
+   * (New API)
+   * `<!-- example(
+   *   {
+   *    "example": "exampleName",
+   *    "file": "example-html.html",
+   *    "lines": [5, 10],
+   *    "expanded": true
+   *   }
+   *  ) -->`
+   *  turns into
+   *  `<div material-docs-example="exampleName"
+   *        file="example-html.html"
+   *        lines="[5, 10]"
+   *        expanded="true"></div>`
    *
-   *  `<!-- example(name) -->` turns into `<div material-docs-example="name"></div>`
+   *  (old API)
+   *  `<!-- example(name) -->`
+   *  turns into
+   *  `<div material-docs-example="name"></div>`
    */
   html(html: string) {
-    html = html.replace(exampleCommentRegex, (_match: string, name: string) =>
-      `<div material-docs-example="${name}"></div>`
-    );
+        html = html.replace(exampleCommentRegex, (_match: string, content: string) => {
+              if (content.startsWith('{')) {
+                  const {example, file, lines, expanded} = JSON.parse(content);
+                  return `<div material-docs-example="${example}"
+                               file="${file}"
+                               lines="${JSON.stringify(lines)}"
+                               expanded="${!!expanded}"></div>`;
+              } else {
+                  return `<div material-docs-example="${content}"></div>`;
+              }
+          }
+        );
 
-    return super.html(html);
-  }
+        return super.html(html);
+    }
 
   /**
    * Method that will be called after a markdown file has been transformed to HTML. This method