class alias tags in html generated from markdown (#3525)

* class alias tags in html generated from markdown

* addressed comments

* address comments

Author: mmalerba

package.json

@@ -68,6 +68,7 @@
     "gulp-clean-css": "^3.0.3",
     "gulp-cli": "^1.2.2",
     "gulp-connect": "^5.0.0",
+    "gulp-dom": "^0.9.17",
     "gulp-flatten": "^0.3.1",
     "gulp-highlight-files": "0.0.4",
     "gulp-htmlmin": "^3.0.0",

tools/gulp/tasks/docs.ts

@@ -9,6 +9,7 @@ const highlight = require('gulp-highlight-files');
 const rename = require('gulp-rename');
 const flatten = require('gulp-flatten');
 const hljs = require('highlight.js');
+const dom  = require('gulp-dom');
 
 // Our docs contain comments of the form `<!-- example(...) -->` which serve as placeholders where
 // example code should be inserted. We replace these comments with divs that have a
@@ -21,6 +22,26 @@ const EXAMPLE_PATTERN = /<!--\W*example\(([^)]+)\)\W*-->/g;
 // documentation page. Using a RegExp to rewrite links in HTML files to work in the docs.
 const LINK_PATTERN = /(<a[^>]*) href="([^"]*)"/g;
 
+// HTML tags in the markdown generated files that should receive a .docs-markdown-${tagName} class
+// for styling purposes.
+const MARKDOWN_TAGS_TO_CLASS_ALIAS = [
+  'a',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'li',
+  'ol',
+  'p',
+  'table',
+  'tbody',
+  'td',
+  'th',
+  'tr',
+  'ul'
+];
+
 task('docs', ['markdown-docs', 'highlight-docs', 'api-docs']);
 
 task('markdown-docs', () => {
@@ -38,6 +59,7 @@ task('markdown-docs', () => {
         }
       }))
       .pipe(transform(transformMarkdownFiles))
+      .pipe(dom(createTagNameAliaser('docs-markdown')))
       .pipe(dest('dist/docs/markdown'));
 });
 
@@ -49,10 +71,10 @@ task('highlight-docs', () => {
   };
 
   return src('src/examples/**/*.+(html|css|ts)')
-    .pipe(flatten())
-    .pipe(rename(renameFile))
-    .pipe(highlight())
-    .pipe(dest('dist/docs/examples'));
+      .pipe(flatten())
+      .pipe(rename(renameFile))
+      .pipe(highlight())
+      .pipe(dest('dist/docs/examples'));
 });
 
 task('api-docs', () => {
@@ -95,3 +117,20 @@ function fixMarkdownDocLinks(link: string, filePath: string): string {
   // guides can be loaded in the Material docs.
   return `guide/${baseName}`;
 }
+
+/**
+ * Returns a function to be called with an HTML document as its context that aliases HTML tags by
+ * adding a class consisting of a prefix + the tag name.
+ * @param classPrefix The prefix to use for the alias class.
+ */
+function createTagNameAliaser(classPrefix: string) {
+  return function() {
+    MARKDOWN_TAGS_TO_CLASS_ALIAS.forEach(tag => {
+      for (let el of this.querySelectorAll(tag)) {
+        el.classList.add(`${classPrefix}-${tag}`);
+      }
+    });
+
+    return this;
+  };
+}