From 1b05432e2f4031af47a078d1e7dfcb2df3281fd7 Mon Sep 17 00:00:00 2001
From: Paul Gschwendtner <paulgschwendtner@gmail.com>
Date: Mon, 23 Jan 2017 20:12:56 +0100
Subject: [PATCH 1/2] fix(docs): properly create links in guide files

* Adds a processor to the `gulp docs` task that can modify links for the Material documentation
* Right now the processor just rewrites `/guides/` paths to `/guide/` and also removes the file extensions. This makes the guides work properly in the documentation.
---
 tools/gulp/tasks/docs.ts | 38 +++++++++++++++++++++++++++++++++++---
 1 file changed, 35 insertions(+), 3 deletions(-)

diff --git a/tools/gulp/tasks/docs.ts b/tools/gulp/tasks/docs.ts
index e6b9fc5021a1..3d4bbb43a011 100644
--- a/tools/gulp/tasks/docs.ts
+++ b/tools/gulp/tasks/docs.ts
@@ -11,6 +11,11 @@ import * as path from 'path';
 // viewer.
 const EXAMPLE_PATTERN = /<!--\W*example\(([^)]+)\)\W*-->/g;
 
+// Markdown files can contain links to other markdown files.
+// Most of those links don't work in the Material docs, because the paths are invalid in the
+// documentation page. Using a RegExp to rewrite links in HTML files to work in the docs.
+const LINK_PATTERN = /(<a[^>]*) href="([^"]*)"/g;
+
 gulp.task('docs', () => {
   return gulp.src(['src/lib/**/*.md', 'guides/*.md'])
       .pipe(markdown({
@@ -25,9 +30,7 @@ gulp.task('docs', () => {
           return code;
         }
       }))
-      .pipe(transform((content: string) =>
-          content.toString().replace(EXAMPLE_PATTERN, (match: string, name: string) =>
-              `<div material-docs-example="${name}"></div>`)))
+      .pipe(transform(transformMarkdownFiles))
       .pipe(gulp.dest('dist/docs'));
 });
 
@@ -37,3 +40,32 @@ task('api', () => {
   const dgeni = new Dgeni([docsPackage]);
   return dgeni.generate();
 });
+
+/** Updates the markdown file's content to work inside of the docs app. */
+function transformMarkdownFiles(buffer: Buffer, file: any): string {
+  let content = buffer.toString('utf-8');
+
+  /* Replace <!-- example(..) --> comments with HTML elements. */
+  content = content.replace(EXAMPLE_PATTERN, (match: string, name: string) =>
+    `<div material-docs-example="${name}"></div>`
+  );
+
+  content = content.replace(LINK_PATTERN, (match: string, pre: string, link: string) =>
+    `${pre} href="${fixMarkdownDocLinks(link, file.path)}"`
+  );
+
+  return content;
+}
+
+/** Fixes paths in the markdown files to work in the material-docs-io. */
+function fixMarkdownDocLinks(link: string, filePath: string): string {
+  if (link.startsWith('http') && filePath.indexOf('guides/') === -1) {
+    return link;
+  }
+
+  let baseName = path.basename(link, path.extname(link));
+
+  // Temporary link the file to the /guide URL because that's the route where the
+  // guides can be loaded in the Material docs.
+  return `guide/${baseName}`;
+}

From 0bc06abf09b3fd36f8017b305deb052ddfaba979 Mon Sep 17 00:00:00 2001
From: Paul Gschwendtner <paulgschwendtner@gmail.com>
Date: Wed, 25 Jan 2017 19:33:31 +0100
Subject: [PATCH 2/2] Adds a comment

---
 tools/gulp/tasks/docs.ts | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/tools/gulp/tasks/docs.ts b/tools/gulp/tasks/docs.ts
index 3d4bbb43a011..ace221fde277 100644
--- a/tools/gulp/tasks/docs.ts
+++ b/tools/gulp/tasks/docs.ts
@@ -50,8 +50,12 @@ function transformMarkdownFiles(buffer: Buffer, file: any): string {
     `<div material-docs-example="${name}"></div>`
   );
 
-  content = content.replace(LINK_PATTERN, (match: string, pre: string, link: string) =>
-    `${pre} href="${fixMarkdownDocLinks(link, file.path)}"`
+  /* Replaces the URL in anchor elements inside of compiled markdown files. */
+  content = content.replace(LINK_PATTERN, (match: string, head: string, link: string) =>
+    // The head is the first match of the RegExp and is necessary to ensure that the RegExp matches
+    // an anchor element. The head will be then used to re-create the existing anchor element.
+    // If the head is not prepended to the replaced value, then the first match will be lost.
+    `${head} href="${fixMarkdownDocLinks(link, file.path)}"`
   );
 
   return content;