chore(docs): correcting headers and adding header linking

guides/getting-started.md

@@ -3,7 +3,7 @@ For help getting started with a new Angular app, check out the
 
 For existing apps, follow these steps to begin using Angular Material.
 
-## Step 1: Install Angular Material and Angular CDK
+### Step 1: Install Angular Material and Angular CDK
 
 ```bash
 npm install --save @angular/material @angular/cdk
@@ -16,7 +16,7 @@ build should not be considered stable and may break between releases.
 npm install --save angular/material2-builds angular/cdk-builds
 ```
 
-## Step 2: Animations
+### Step 2: Animations
 
 Some Material components depend on the Angular animations module in order to be able to do
 more advanced transitions. If you want these animations to work in your app, you have to
@@ -50,7 +50,7 @@ import {NoopAnimationsModule} from '@angular/platform-browser/animations';
 export class PizzaPartyAppModule { }
 ```
 
-## Step 3: Import the component modules
+### Step 3: Import the component modules
 
 Import the NgModule for each component you want to use: 
 
@@ -82,7 +82,7 @@ export class MyOwnCustomMaterialModule { }
 Whichever approach you use, be sure to import the Angular Material modules _after_ Angular's 
 `BrowserModule`, as the import order matters for NgModules.
 
-## Step 4: Include a theme
+### Step 4: Include a theme
 
 Including a theme is **required** to apply all of the core and theme styles to your application.
 
@@ -98,7 +98,7 @@ your `index.html`.
 For more information on theming and instructions on how to create a custom theme, see the
 [theming guide](./theming.md).
 
-## Step 5: Gesture Support
+### Step 5: Gesture Support
 
 Some components (`md-slide-toggle`, `md-slider`, `mdTooltip`) rely on
 [HammerJS](http://hammerjs.github.io/) for gestures. In order to get the full feature-set of these
@@ -118,7 +118,7 @@ After installing, import it on your app's root module.
 import 'hammerjs';
 ```
 
-## Step 6 (Optional): Add Material Icons
+### Step 6 (Optional): Add Material Icons
 
 If you want to use the `md-icon` component with the official 
 [Material Design Icons](https://material.io/icons/), load the icon font in your `index.html`.
@@ -133,7 +133,7 @@ For more information on using Material Icons, check out the
 Note that `md-icon` supports any font or svg icons; using Material Icons is one of many options.
 
 
-## Appendix: Configuring SystemJS
+### Appendix: Configuring SystemJS
 
 If your project is using SystemJS for module loading, you will need to add `@angular/material` and
 `@angular/cdk` to the SystemJS configuration:
@@ -151,6 +151,6 @@ System.config({
 ```
 
 
-## Example Angular Material projects
+### Example Angular Material projects
 - [material.angular.io](https://material.angular.io) -
 We build our own documentation with Angular Material!

guides/theming-your-components.md

@@ -1,13 +1,13 @@
 # Theming your custom components
 In order to style your own components with Angular Material's tooling, the component's styles must be defined with Sass.
 
-## Using `@mixin` to automatically apply a theme
+### Using `@mixin` to automatically apply a theme
 
-### Why using `@mixin`
+#### Why using `@mixin`
 The advantage of using a `@mixin` function is that when you change your theme, every file that uses it will be updated automatically.
 Calling it with a different theme argument allow multiple themes within the app or component.
 
-### How to use `@mixin`
+#### How to use `@mixin`
 We can better theming our custom components adding a `@mixin` function to its theme file and then calling this function to apply a theme.
 
 All you need is to create a `@mixin` function in the custom-component-theme.scss
@@ -44,15 +44,15 @@ Now you just have to call the `@mixin` function to apply the theme:
 For more details about the theming functions, see the comments in the
 [source](https://github.com/angular/material2/blob/master/src/lib/core/theming/_theming.scss).
 
-### Best practices using `@mixin`
+#### Best practices using `@mixin`
 When using `@mixin`, the theme file should only contain the definitions that are affected by the passed-in theme.
 
 All styles that are not affected by the theme should be placed in a `candy-carousel.scss` file. This file should contain everything that is not affected by the theme like sizes, transitions...
 
 Styles that are affected by the theme should be placed in a separated theming file as `_candy-carousel-theme.scss` and the file should have a `_` before the name. This file should contain the `@mixin` function responsible for applying the theme to the component.
 
 
-## Using colors from a palette
+### Using colors from a palette
 You can consume the theming functions and Material palette variables from `@angular/material/theming`.
 You can use the `mat-color` function to extract a specific color from a palette. For example:
 

src/lib/autocomplete/autocomplete.md

@@ -148,7 +148,7 @@ class MyComp {
 ```
 
 
-#### Keyboard interaction:
+### Keyboard interaction
 - <kbd>DOWN_ARROW</kbd>: Next option becomes active.
 - <kbd>UP_ARROW</kbd>: Previous option becomes active.
 - <kbd>ENTER</kbd>: Select currently active item.

src/lib/select/select.md

@@ -78,7 +78,7 @@ Here are the available global options:
 | --------------- | ------- | ------------------- | ----------------------------------------- |
 | float           | string  | auto, always, never | The default placeholder float behavior.   |
 
-#### Keyboard interaction:
+### Keyboard interaction
 - <kbd>DOWN_ARROW</kbd>: Focus next option
 - <kbd>UP_ARROW</kbd>: Focus previous option
 - <kbd>ENTER</kbd> or <kbd>SPACE</kbd>: Select focused item

src/lib/snack-bar/snack-bar.md

@@ -48,7 +48,7 @@ snackbar.open('Message archived', 'Undo', {
 });
 ```
 
-### Sharing data with a custom snack-bar.
+### Sharing data with a custom snack-bar
 You can share data with the custom snack-bar, that you opened via the `openFromComponent` method,
 by passing it through the `data` property.
 

src/material-examples/example-data.ts

@@ -7,7 +7,7 @@ import {EXAMPLE_COMPONENTS} from './example-module';
  */
 export class ExampleData {
   // TODO: figure out how do we get these variables.
-  description: string = 'Some description for material';
+  description = 'Some description for material';
   // TODO: use real example and delete the example/ folder.
   examplePath = '/assets/example/';
   exampleFiles = ['button-demo.html', 'button-demo.scss', 'button-demo.ts'];

tools/gulp/tasks/docs.ts

@@ -69,10 +69,25 @@ task('docs', [
 
 /** Generates html files from the markdown overviews and guides. */
 task('markdown-docs', () => {
+  // Extend the renderer for custom heading anchor rendering
+  markdown.marked.Renderer.prototype.heading = (text: string, level: number): string => {
+    if (level === 3 || level === 4) {
+      const escapedText = text.toLowerCase().replace(/[^\w]+/g, '-');
+      return `
+        <h${level} id="${escapedText}" class="docs-header-link">
+          <div header-link="${escapedText}"></div>
+          ${text}
+        </h${level}>
+      `;
+    } else {
+      return `<h${level}>${text}</h${level}>`;
+    }
+  };
+
   return src(['src/lib/**/*.md', 'src/cdk/**/*.md', 'guides/*.md'])
       .pipe(markdown({
         // Add syntax highlight using highlight.js
-        highlight: (code: string, language: string) => {
+        highlight: (code: string, language: string): string => {
           if (language) {
             // highlight.js expects "typescript" written out, while Github supports "ts".
             let lang = language.toLowerCase() === 'ts' ? 'typescript' : language;