docs: create anchors for all header elems & fix a11y in guides (#21751)

- Lighthouse's a11y audit wants page headers to progress in order - https://web.dev/heading-order/ - Go through all guides and make the headers consistent - and ordered to pass the a11y audit - fix grammar issues and typos (cherry picked from commit 9db31ee)
angular · Feb 5, 2021 · ad8c8ac · ad8c8ac
1 parent eeb77f0
commit ad8c8ac
Show file tree

Hide file tree

Showing 14 changed files with 256 additions and 227 deletions.
diff --git a/guides/bidirectionality.md b/guides/bidirectionality.md
@@ -1,14 +1,16 @@
 # Angular Material bi-directionality
 
-### Setting a text-direction for your application
+## Setting a text-direction for your application
+
 The [`dir` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir)
 is typically applied to `<html>` or `<body>` element of a page. However, it can be used on any
 element, within your Angular app, to apply a text-direction to a smaller subset of the page.
 
 All Angular Material components automatically reflect the LTR/RTL direction
 of their container.
 
-### Reading the text-direction in your own components
+## Reading the text-direction in your own components
+
 `@angular/cdk/bidi` provides a `Directionality` injectable that can be used by any component
 in your application. To consume it, you must import `BidiModule` from `@angular/cdk/bidi`.
 
@@ -18,7 +20,8 @@ in your application. To consume it, you must import `BidiModule` from `@angular/
 captures changes from `dir` attributes _inside the Angular application context_. It will not
 emit for changes to `dir` on `<html>` and `<body>`, as they are assumed to be static.
 
-#### Example
+### Example
+
 ```ts
 @Component({ /* ... */ })
 export class MyCustomComponent {

diff --git a/guides/creating-a-custom-form-field-control.md b/guides/creating-a-custom-form-field-control.md
@@ -72,7 +72,7 @@ export class MyTelInput {
 }
 ```
 
-### Providing our component as a MatFormFieldControl
+## Providing our component as a MatFormFieldControl
 
 The first step is to provide our new component as an implementation of the `MatFormFieldControl`
 interface that the `<mat-form-field>` knows how to work with. To do this, we will have our class
@@ -91,7 +91,7 @@ export class MyTelInput implements MatFormFieldControl<MyTel> {
 }
 ```
 
-This sets up our component so it can work with `<mat-form-field>`, but now we need to implement the
+This sets up our component, so it can work with `<mat-form-field>`, but now we need to implement the
 various methods and properties declared by the interface we just implemented. To learn more about
 the `MatFormFieldControl` interface, see the
 [form field API documentation](https://material.angular.io/components/form-field/api).
@@ -185,7 +185,7 @@ constructor(
 
 Note that if your component implements `ControlValueAccessor`, it may already be set up to provide
 `NG_VALUE_ACCESSOR` (in the `providers` part of the component's decorator, or possibly in a module
-declaration). If so you may get a *cannot instantiate cyclic dependency* error.
+declaration). If so, you may get a *cannot instantiate cyclic dependency* error.
 
 To resolve this, remove the `NG_VALUE_ACCESSOR` provider and instead set the value accessor directly:
 
@@ -224,7 +224,7 @@ For additional information about `ControlValueAccessor` see the [API docs](https
 
 #### `focused`
 
-This property indicates whether or not the form field control should be considered to be in a
+This property indicates whether the form field control should be considered to be in a
 focused state. When it is in a focused state, the form field is displayed with a solid color
 underline. For the purposes of our component, we want to consider it focused if any of the part
 inputs are focused. We can use the `FocusMonitor` from `@angular/cdk` to easily check this. We also
@@ -250,7 +250,7 @@ ngOnDestroy() {
 #### `empty`
 
 This property indicates whether the form field control is empty. For our control, we'll consider it
-empty if all of the parts are empty.
+empty if all the parts are empty.
 
 ```ts
 get empty() {
@@ -263,7 +263,7 @@ get empty() {
 
 This property is used to indicate whether the label should be in the floating position. We'll
 use the same logic as `matInput` and float the placeholder when the input is focused or non-empty.
-Since the placeholder will be overlapping our control when when it's not floating, we should hide
+Since the placeholder will be overlapping our control when it's not floating, we should hide
 the `–` characters when it's not floating.
 
 ```ts
@@ -329,7 +329,7 @@ errorState = false;
 #### `controlType`
 
 This property allows us to specify a unique string for the type of control in form field. The
-`<mat-form-field>` will add an additional class based on this type that can be used to easily apply
+`<mat-form-field>` will add a class based on this type that can be used to easily apply
 special styles to a `<mat-form-field>` that contains a specific type of control. In this example
 we'll use `example-tel-input` as our control type which will result in the form field adding the
 class `mat-form-field-type-example-tel-input`.
@@ -422,15 +422,15 @@ export class MyTelInput implements MatFormFieldControl<MyTel> {
 ### Trying it out
 
 Now that we've fully implemented the interface, we're ready to try our component out! All we need to
-do is place it inside of a `<mat-form-field>`
+do is place it inside a `<mat-form-field>`
 
 ```html
 <mat-form-field>
   <example-tel-input></example-tel-input>
 </mat-form-field>
 ```
 
-We also get all of the features that come with `<mat-form-field>` such as floating placeholder,
+We also get all the features that come with `<mat-form-field>` such as floating placeholder,
 prefix, suffix, hints, and errors (if we've given the form field an `NgControl` and correctly report
 the error state).
 

diff --git a/guides/creating-a-custom-stepper-using-the-cdk-stepper.md b/guides/creating-a-custom-stepper-using-the-cdk-stepper.md
@@ -100,7 +100,7 @@ In the `app.component.css` file we can now style the stepper however we want:
 
 ## Using our new custom stepper component
 
-Now we are ready to use our new custom stepper component and fill it with steps. Therefore we can, for example, add it to our `app.component.html` and define some steps:
+Now we are ready to use our new custom stepper component and fill it with steps. Therefore, we can, for example, add it to our `app.component.html` and define some steps:
 
 **app.component.html**
 

diff --git a/guides/customizing-component-styles.md b/guides/customizing-component-styles.md
@@ -1,6 +1,6 @@
 # Customizing Angular Material component styles
 
-### Styling concepts
+## Styling concepts
 
 There are 3 questions to keep in mind while customizing the styles of Angular Material
 components:
@@ -9,7 +9,7 @@ components:
 2. Are your styles more specific than the defaults?
 3. Is the component a child of your component, or does it exist elsewhere in the DOM?
 
-##### View encapsulation
+### View encapsulation
 
 By default, Angular component styles are scoped to affect the component's view. This means that
 the styles you write will affect all the elements in your component template. They will *not*
@@ -20,23 +20,23 @@ also wish to take a look at
 [_The State of CSS in Angular_](https://blog.angular.io/the-state-of-css-in-angular-4a52d4bd2700)
 on the Angular blog.
 
-##### Selector specificity
+### Selector specificity
 
 Each CSS declaration has a level of *specificity* based on the type and number of selectors used.
 More specific styles will take precedence over less specific styles. Angular Material uses the
 least specific selectors possible for its components in order to make it easy to override them.
 You can read more about specificity and how it is calculated on the
 [MDN web docs](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity).
 
-##### Component location
+### Component location
 
-Some Angular Material components, specifically overlay-based ones like MatDialog, MatSnackbar, etc.,
+Some Angular Material components, specifically overlay-based one's like MatDialog, MatSnackbar, etc.,
 do not exist as children of your component. Often they are injected elsewhere in the DOM. This is
 important to keep in mind, since even using high specificity and shadow-piercing selectors will
 not target elements that are not direct children of your component. Global styles are recommended
 for targeting such components.
 
-### Styling overlay components
+## Styling overlay components
 
 Overlay-based components have a `panelClass` property (or similar) that can be used to target the
 overlay pane. For example, to remove the padding from a dialog:
@@ -52,12 +52,12 @@ overlay pane. For example, to remove the padding from a dialog:
 this.dialog.open(MyDialogComponent, {panelClass: 'myapp-no-padding-dialog'})
 ```
 
-Since you are adding the styles to your global stylesheet, it is good practice to scope
+Since you are adding the styles to your global stylesheet, it is a good practice to scope
 them appropriately. Try prefixing your selector with your app name or "custom". Also note that
 the `mat-dialog-container`'s padding is added by default via a selector with specificity of 1. The
 customizing styles have a specificity of 2, so they will always take precedence.
 
-### Styling other components
+## Styling other components
 
 If your component has view encapsulation turned on (default), your component styles will only
 affect the top level children in your template. HTML elements belonging to child components cannot

diff --git a/guides/duplicate-theming-styles.md b/guides/duplicate-theming-styles.md
@@ -63,7 +63,7 @@ extract the configuration for the color system from the theme.
 }
 ```
 
-#### Disabling duplication warnings
+## Disabling duplication warnings
 
 If your application intentionally duplicates styles, a global Sass variable can be
 set to disable duplication warnings from Angular Material. For example:

diff --git a/guides/elevation.md b/guides/elevation.md
@@ -1,3 +1,5 @@
+# Setting Element Elevation
+
 Angular Material's elevation classes and mixins allow you to add separation between elements along
 the z-axis. All material design elements have resting elevations. In addition, some elements may
 change their elevation in response to user interaction. The
@@ -7,7 +9,7 @@ explains how to best use elevation.
 Angular Material provides two ways to control the elevation of elements: predefined CSS classes
 and mixins.
 
-### Predefined CSS classes
+## Predefined CSS classes
 
 The easiest way to add elevation to an element is to simply add one of the predefined CSS classes
 `mat-elevation-z#` where `#` is the elevation number you want, 0-24. Dynamic elevation can be
@@ -19,7 +21,7 @@ achieved by switching elevation classes:
 
 <!-- example(elevation-overview) -->
 
-### Mixins
+## Mixins
 
 Elevations can also be added in CSS via the `mat-elevation` mixin, which takes a number 0-24
 indicating the elevation of the element as well as optional arguments for the elevation shadow's

diff --git a/guides/getting-started.md b/guides/getting-started.md
@@ -1,16 +1,16 @@
 # Getting Started with Angular Material
 
-This guide explains how to setup your Angular project to begin using Angular Material. It includes information on prerequisites, installing Angular Material, and optionally displaying a sample material component in your application to verify your setup.
+This guide explains how to set up your Angular project to begin using Angular Material. It includes information on prerequisites, installing Angular Material, and optionally displaying a sample material component in your application to verify your setup.
 
 *Angular Resources*
 
 If you are new to Angular or getting started with a new Angular application, see [Angular's full Getting Started Guide](https://angular.io/start) and [Setting up your environment](https://angular.io/guide/setup-local).
 
 For existing applications, follow the steps below to begin using Angular Material.
 
-### Install Angular Material
+## Install Angular Material
 
-Use the Angular CLI's install [schematic](https://material.angular.io/guide/schematics) to set up your Angular Material project by running the following command:
+Use the Angular CLI's installation [schematic](https://material.angular.io/guide/schematics) to set up your Angular Material project by running the following command:
 
 ```bash
 ng add @angular/material
@@ -71,8 +71,8 @@ Run your local dev server:
 ng serve
 ```
 
-and point your browser to [http://localhost:4200](http://localhost:4200)
+Then point your browser to [http://localhost:4200](http://localhost:4200)
 
 You should see the material slider component on the page.
 
-In addition to the install schematic, Angular Material comes with [several schematics](https://material.angular.io/guide/schematics) (like nav, table, address-form, etc.) that can be used to easily generate pre-built components in your application.
+In addition to the installation schematic, Angular Material comes with [several schematics](https://material.angular.io/guide/schematics) (like nav, table, address-form, etc.) that can be used to easily generate pre-built components in your application.
diff --git a/guides/schematics.md b/guides/schematics.md
@@ -1,13 +1,16 @@
+# Installation and Code Generation
+
 Angular Material comes packaged with Angular CLI schematics to make
 creating Material applications easier.
 
-### Install Schematics
+## Install Schematics
+
 Schematics are included with both `@angular/cdk` and `@angular/material`. Once you install the npm
 packages, they will be available through the Angular CLI.
 
 Using the command below will install Angular Material, the [Component Dev Kit](https://material.angular.io/cdk) (CDK),
 and [Angular Animations](https://angular.io/guide/animations) in your project. Then it will run the
-install schematic.
+installation schematic.
 
 ```
 ng add @angular/material
@@ -19,7 +22,7 @@ In case you just want to install the `@angular/cdk`, there are also schematics f
 ng add @angular/cdk
 ```
 
-The Angular Material `ng add` schematic helps you setup an Angular CLI project that uses Material. Running `ng add` will:
+The Angular Material `ng add` schematic helps you set up an Angular CLI project that uses Material. Running `ng add` will:
 
 - Ensure [project dependencies](./getting-started#step-1-install-angular-material-angular-cdk-and-angular-animations) are placed in `package.json`
 - Enable the [BrowserAnimationsModule](./getting-started#step-2-configure-animations) your app module
@@ -33,7 +36,8 @@ The Angular Material `ng add` schematic helps you setup an Angular CLI project t
 
 
 ## Component schematics
-In addition to the install schematic, Angular Material comes with multiple schematics that can be
+
+In addition to the installation schematic, Angular Material comes with multiple schematics that can be
 used to easily generate Material Design components:
 
 
@@ -46,14 +50,14 @@ used to easily generate Material Design components:
 | `tree`         | Component that interactively visualizes a nested folder structure by using the `<mat-tree>` component  |
 
 
-Additionally the Angular CDK also comes with a collection of component schematics:
+Additionally, the Angular CDK also comes with a collection of component schematics:
 
 
 | Name           | Description                                                                                        |
 |----------------|----------------------------------------------------------------------------------------------------|
 | `drag-drop`    | Component that uses the `@angular/cdk/drag-drop` directives for creating an interactive to-do list |
 
-#### Address form schematic
+### Address form schematic
 
 Running the `address-form` schematic generates a new Angular component that can be used to get
 started with a Material Design form group consisting of:
@@ -66,40 +70,45 @@ started with a Material Design form group consisting of:
 ng generate @angular/material:address-form <component-name>
 ```
 
-#### Navigation schematic
+### Navigation schematic
+
 The `navigation` schematic will create a new component that includes
-a toolbar with the app name and a responsive side nav based on Material
+a toolbar with the app name, and a responsive side nav based on Material
 breakpoints.
 
 ```
 ng generate @angular/material:navigation <component-name>
 ```
 
-#### Table schematic
+### Table schematic
+
 The table schematic will create a component that renders an Angular Material `<table>` which has
 been pre-configured with a datasource for sorting and pagination.
 
 ```
 ng generate @angular/material:table <component-name>
 ```
 
-#### Dashboard schematic
+### Dashboard schematic
+
 The `dashboard` schematic will create a new component that contains
 a dynamic grid list of Material Design cards.
 
 ```
 ng generate @angular/material:dashboard <component-name>
 ```
 
-#### Tree schematic
+### Tree schematic
+
 The `tree` schematic can be used to quickly generate an Angular component that uses the Angular
 Material `<mat-tree>` component to visualize a nested folder structure.
 
 ```
 ng generate @angular/material:tree <component-name>
 ```
 
-#### Drag and Drop schematic
+### Drag and Drop schematic
+
 The `drag-drop` schematic is provided by the `@angular/cdk` and can be used to generate a component
 that uses the CDK drag and drop directives.
 

diff --git a/guides/theming-your-components.md b/guides/theming-your-components.md
@@ -1,8 +1,10 @@
-### Theming your custom component with Angular Material's theming system
+# Theming your custom component with Angular Material's theming system
+
 In order to style your own components with Angular Material's tooling, the component's styles must
 be defined with Sass.
 
-#### 1. Define all color and typography styles in a "theme file" for the component
+## 1. Define all color and typography styles in a "theme file" for the component
+
 First, create a Sass mixin that accepts an Angular Material color configuration and
 outputs the color-specific styles for the component. A color configuration is a Sass map.
 
@@ -70,12 +72,14 @@ individual theming systems (`color` and `typography`).
 See the [typography guide](https://material.angular.io/guide/typography) for more information on
 typographic customization.
 
-#### 2. Define all remaining styles in a normal component stylesheet.
+## 2. Define all remaining styles in a normal component stylesheet
+
 Define all styles unaffected by the theme in a separate file referenced directly in the component's
 `styleUrl`.  This generally includes everything except for color and typography styles.
 
 
-#### 3. Include the theme mixin in your application
+## 3. Include the theme mixin in your application
+
 Use the Sass `@include` keyword to include a component's theme mixin wherever you're already
 including Angular Material's built-in theme mixins. 
 
@@ -104,7 +108,8 @@ $theme: mat-light-theme((
 ```
 
 
-#### Note: using the `mat-color` function to extract colors from a palette
+## Note: using the `mat-color` function to extract colors from a palette
+
 You can consume the theming functions and Material Design color palettes from
 `@angular/material/theming`. The `mat-color` Sass function extracts a specific color from a palette.
 For example: