chore: add gulp task to convert markdown to html (#1821)

Author: mmalerba

package.json

@@ -59,10 +59,12 @@
     "gulp-autoprefixer": "^3.1.1",
     "gulp-clean": "^0.3.2",
     "gulp-cli": "^1.2.2",
+    "gulp-markdown": "^1.2.0",
     "gulp-sass": "^2.3.2",
     "gulp-server-livereload": "^1.8.2",
     "gulp-shell": "^0.5.2",
     "gulp-sourcemaps": "^1.6.0",
+    "gulp-transform": "^1.1.0",
     "gulp-typescript": "^2.13.6",
     "jasmine-core": "^2.4.1",
     "karma": "^1.1.1",

src/lib/button/README.md

@@ -40,6 +40,8 @@ between the tags, as you would with a normal button.
 
 Example:
 
+<!-- example(my example) -->
+
  ```html
 <button md-button>FLAT</button>
 <button md-raised-button>RAISED</button>
@@ -67,6 +69,8 @@ In flat buttons, the palette chosen will affect the text color, while in other b
 
 Example:
 
+<!-- example(my other example) -->
+
  ```html
 <button md-raised-button color="primary">PRIMARY</button>
 <button md-raised-button color="accent">ACCENT</button>

tools/gulp/gulpfile.ts

@@ -3,6 +3,7 @@ import './tasks/clean';
 import './tasks/components';
 import './tasks/default';
 import './tasks/development';
+import './tasks/docs';
 import './tasks/e2e';
 import './tasks/lint';
 import './tasks/release';

tools/gulp/tasks/docs.ts

@@ -0,0 +1,20 @@
+import gulp = require('gulp');
+const markdown = require('gulp-markdown');
+const transform = require('gulp-transform');
+
+
+// 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
+// `material-docs-example` attribute which can be used to locate the divs and initialize the example
+// viewer.
+const EXAMPLE_PATTERN = /<!--\W*example\(([^)]+)\)\W*-->/g;
+
+
+gulp.task('docs', () => {
+  return gulp.src(['src/lib/**/*.md'])
+      .pipe(markdown())
+      .pipe(transform((content: string) =>
+          content.toString().replace(EXAMPLE_PATTERN, (match: string, name: string) =>
+              `<div material-docs-example="${name}"></div>`)))
+      .pipe(gulp.dest('dist/docs'));
+});