docs(): title elements will be auto anchored. (#9681)

* Very often I want to link a user to a specific topic in the docs, but it is just not possible, and they needed to search for the topic I meant manually

* Having a directive, which automatically creates anchors for all title elements does make this SUPER easy, and we can just send the user a easy (accessible) link.

> Note that the GitHub Readme works kind of the same.

Author: devversion

docs/app/css/style.css

@@ -29,6 +29,10 @@ body.docs-body {
   height: auto;
 }
 
+.docs-anchor {
+  color: inherit;
+}
+
 #license-footer {
   align-self: flex-end;
   padding: 16px 32px;

docs/app/js/anchor.js

@@ -0,0 +1,45 @@
+(function() {
+  angular
+    .module('docsApp')
+    .directive('h4', MdAnchorDirective)
+    .directive('h3', MdAnchorDirective)
+    .directive('h2', MdAnchorDirective)
+    .directive('h1', MdAnchorDirective);
+
+  function MdAnchorDirective($mdUtil) {
+
+    /** @const @type {RegExp} */
+    var unsafeCharRegex = /[&\s+$,:;=?@"#{}|^~[`%!'\].\/()*\\]/g;
+
+    return {
+      restrict: 'E',
+      scope: {},
+      template: '<a class="docs-anchor" ng-href="#{{ name }}" name="{{ name }}" ng-transclude></a>',
+      transclude: true,
+      link: postLink
+    };
+
+    function postLink(scope, element) {
+
+      // Delay the URL creation, because the inner text might be not interpolated yet.
+      $mdUtil.nextTick(createContentURL);
+
+      /**
+       * Creates URL from the text content of the element and writes it into the scope.
+       */
+      function createContentURL() {
+        scope.name = element.text()
+          .trim()                           // Trim text due to browsers extra whitespace.
+          .replace(/'/g, '')                // Transform apostrophes words to a single one.
+          .replace(unsafeCharRegex, '-')    // Replace unsafe chars with a dash symbol.
+          .replace(/-{2,}/g, '-')           // Remove repeating dash symbols.
+          .replace(/^-|-$/g, '')            // Remove preceding or ending dashes.
+          .toLowerCase();                   // Link should be lower-case for accessible URL.
+      }
+    }
+  }
+
+  // Manually specify $inject because Strict DI is enabled.
+  MdAnchorDirective.$inject = ['$mdUtil'];
+
+})();

docs/app/js/app.js

@@ -127,6 +127,11 @@ function(SERVICES, COMPONENTS, DEMOS, PAGES,
   });
 
   $routeProvider.otherwise('/');
+
+  // Change hash prefix of the Angular router, because we use the hash symbol for anchor links.
+  // The hash will be not used by the docs, because we use the HTML5 mode for our links.
+  $locationProvider.hashPrefix('!');
+
 }])
 
 .config(['AngularyticsProvider', function(AngularyticsProvider) {

docs/gulpfile.js

@@ -125,6 +125,7 @@ gulp.task('docs-js', ['docs-app', 'docs-html2js', 'demos', 'build', 'docs-js-dep
   return series(
     gulp.src([
       'node_modules/angularytics/dist/angularytics.js',
+      'dist/docs/js/app.js', // Load the Angular module initialization at first.
       'dist/docs/js/**/*.js'
     ])
       .pipe(concat('docs.js'))