From f5dc120fd786120290505fb2b7c6ab17f2567a3e Mon Sep 17 00:00:00 2001 From: Austin Date: Tue, 1 Aug 2017 16:17:51 -0500 Subject: [PATCH] chore(docs): correcting headers and adding header linking (#6040) * chore(*): correcting headers and adding header linking * chore(*): add specific class name * Update docs.ts --- guides/getting-started.md | 16 ++++++++-------- guides/theming-your-components.md | 10 +++++----- src/lib/autocomplete/autocomplete.md | 2 +- src/lib/select/select.md | 2 +- src/lib/snack-bar/snack-bar.md | 2 +- src/material-examples/example-data.ts | 2 +- tools/gulp/tasks/docs.ts | 17 ++++++++++++++++- 7 files changed, 33 insertions(+), 18 deletions(-) diff --git a/guides/getting-started.md b/guides/getting-started.md index c9711abe84e..15e07681aa5 100644 --- a/guides/getting-started.md +++ b/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. @@ -161,6 +161,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! diff --git a/guides/theming-your-components.md b/guides/theming-your-components.md index 1000151cd4b..420a0379025 100644 --- a/guides/theming-your-components.md +++ b/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,7 +44,7 @@ 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... @@ -52,7 +52,7 @@ All styles that are not affected by the theme should be placed in a `candy-carou 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: diff --git a/src/lib/autocomplete/autocomplete.md b/src/lib/autocomplete/autocomplete.md index d7c23e70db9..2ae1b6d6ca8 100644 --- a/src/lib/autocomplete/autocomplete.md +++ b/src/lib/autocomplete/autocomplete.md @@ -78,7 +78,7 @@ Then bind it to the autocomplete's `displayWith` property. -#### Keyboard interaction: +### Keyboard interaction - DOWN_ARROW: Next option becomes active. - UP_ARROW: Previous option becomes active. - ENTER: Select currently active item. diff --git a/src/lib/select/select.md b/src/lib/select/select.md index 0379498417c..4e683475ebd 100644 --- a/src/lib/select/select.md +++ b/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 - DOWN_ARROW: Focus next option - UP_ARROW: Focus previous option - ENTER or SPACE: Select focused item diff --git a/src/lib/snack-bar/snack-bar.md b/src/lib/snack-bar/snack-bar.md index 9054620e02d..5e2ac1b1fa2 100644 --- a/src/lib/snack-bar/snack-bar.md +++ b/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. diff --git a/src/material-examples/example-data.ts b/src/material-examples/example-data.ts index 3dd2b5a3ef4..f053682199e 100644 --- a/src/material-examples/example-data.ts +++ b/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']; diff --git a/tools/gulp/tasks/docs.ts b/tools/gulp/tasks/docs.ts index bf3e8adbe10..0751d594967 100644 --- a/tools/gulp/tasks/docs.ts +++ b/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 ` + +
+ ${text} + + `; + } else { + return `${text}`; + } + }; + 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;